@trycore/spec-build-harness 0.8.5 → 0.11.0

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

@@ -0,0 +1,625 @@
+#!/usr/bin/env bash
+# runtime-client.sh — cliente bash del Agent Orchestrator Runtime [EP-OR-08-A].
+# Diseño: fail-open, igual que state-io.sh/config.sh. Ninguna función bloquea ni lanza;
+# ante red caída, curl/python3 ausentes, JSON corrupto o timeout, degrada a un valor
+# vacío/código distinguible y jamás corrompe el estado local.
+# Contrato de red: docs/runtime/protocolo-cliente-runtime.md + spec §3.1/§4.1-A.
+
+source "$(dirname "${BASH_SOURCE[0]}")/config.sh"
+
+# runtime_mode — TRYCORE_RUNTIME_MODE (env) > runtime.mode (config) > "legacy".
+# En "legacy" ninguna función de red debe invocarse desde un guard/hook. Normaliza
+# cualquier valor que no sea exactamente "dual"/"runtime" a "legacy" — un valor inválido
+# o mal escrito (typo, mayúscula) debe fallar HACIA el modo seguro, nunca hacia la red.
+runtime_mode() {
+  local m
+  if [ -n "${TRYCORE_RUNTIME_MODE:-}" ]; then
+    m="$TRYCORE_RUNTIME_MODE"
+  else
+    m="$(config_get runtime.mode legacy)"
+  fi
+  case "$m" in
+    dual|runtime) echo "$m" ;;
+    *) echo legacy ;;
+  esac
+}
+
+runtime_credentials_path() {
+  echo "$(config_root)/.claude/state/runtime.credentials"
+}
+
+# runtime_field <clave> — lee un campo del fichero de credenciales. Vacío si falta.
+runtime_field() {
+  local key="$1" file
+  file="$(runtime_credentials_path)"
+  [ -f "$file" ] || { echo ""; return; }
+  command -v python3 >/dev/null 2>&1 || { echo ""; return; }
+  python3 - "$file" "$key" <<'PY' 2>/dev/null
+import json,sys
+file,key=sys.argv[1],sys.argv[2]
+try:
+    d=json.load(open(file))
+    v=d.get(key)
+    print(v if v is not None else "")
+except Exception:
+    print("")
+PY
+}
+
+# runtime_credentials_merge <json> — hace upsert de las claves del fragmento sobre el
+# fichero existente (o uno nuevo). Escritura atómica + chmod 0600. Nunca imprime el token.
+runtime_credentials_merge() {
+  local fragment="$1" file dir
+  file="$(runtime_credentials_path)"
+  dir="$(dirname "$file")"
+  mkdir -p "$dir"
+  command -v python3 >/dev/null 2>&1 || return 1
+  python3 - "$file" "$fragment" <<'PY' 2>/dev/null || return 1
+import json,sys,os,tempfile
+path,frag=sys.argv[1],sys.argv[2]
+try:
+    d=json.load(open(path)) if os.path.exists(path) else {}
+except Exception:
+    d={}
+if not isinstance(d,dict):
+    d={}
+d.update(json.loads(frag))
+dirn=os.path.dirname(path) or "."
+fd,tmp=tempfile.mkstemp(dir=dirn,prefix=".runtime-credentials.",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.chmod(tmp,0o600)
+    os.replace(tmp,path)
+except Exception:
+    try: os.unlink(tmp)
+    except OSError: pass
+    raise
+PY
+}
+
+runtime_url() {
+  runtime_field runtime_url
+}
+
+# runtime_status_file — fichero de estado para el código HTTP de la última llamada.
+# NO se usa una variable global: toda función de este cliente se invoca vía sustitución
+# de comandos (`body="$(runtime_get ...)"`), que bash ejecuta en una subshell — cualquier
+# asignación de variable dentro de esa subshell se pierde al volver al shell padre. Un
+# fichero en disco sí sobrevive ese límite (mismo principio que context.lock/credentials).
+runtime_status_file() {
+  echo "$(config_root)/.claude/state/.runtime-http-status"
+}
+
+# runtime_http_status — código HTTP de la última llamada a runtime_get/runtime_post.
+runtime_http_status() {
+  local sfile; sfile="$(runtime_status_file)"
+  [ -f "$sfile" ] && cat "$sfile" || echo "000"
+}
+
+# _runtime_http <METHOD> <path> [body] — primitivo interno. Nunca lanza; ante fallo de
+# red/curl/python3 deja runtime_http_status()=000 y stdout vacío. El body SIEMPRE se
+# manda vía `--data-binary @fichero` (nunca `-d "$body"` directo): un body en argv está
+# limitado por ARG_MAX del sistema (~1 MB típico) — con la cota del outbox en 5 MB
+# (Task 8) un lote grande superaría ese límite y curl fallaría en silencio, fail-open,
+# sin drenar nunca la cola. Un fichero no tiene ese límite.
+_runtime_http() {
+  local method="$1" path="$2" body="${3:-}" url token tmp bodyfile status rc sfile
+  url="$(runtime_url)${path}"
+  token="$(runtime_field project_token)"
+  sfile="$(runtime_status_file)"
+  mkdir -p "$(dirname "$sfile")"
+  if [ -z "$(runtime_url)" ] || ! command -v curl >/dev/null 2>&1; then
+    printf '000' > "$sfile"
+    return 1
+  fi
+  tmp="$(mktemp)" || { printf '000' > "$sfile"; return 1; }
+  if [ -n "$body" ]; then
+    bodyfile="$(mktemp)" || { printf '000' > "$sfile"; rm -f "$tmp"; return 1; }
+    printf '%s' "$body" > "$bodyfile"
+    status="$(curl -sS -m 10 -o "$tmp" -w '%{http_code}' -X "$method" "$url" \
+      -H "Authorization: Bearer $token" -H 'Content-Type: application/json' \
+      --data-binary "@$bodyfile" 2>/dev/null)"
+    rc=$?
+    rm -f "$bodyfile"
+  else
+    status="$(curl -sS -m 10 -o "$tmp" -w '%{http_code}' -X "$method" "$url" \
+      -H "Authorization: Bearer $token" 2>/dev/null)"
+    rc=$?
+  fi
+  if [ $rc -ne 0 ] || [ -z "$status" ]; then
+    printf '000' > "$sfile"
+    rm -f "$tmp"
+    return 1
+  fi
+  printf '%s' "$status" > "$sfile"
+  cat "$tmp"
+  rm -f "$tmp"
+  return 0
+}
+
+runtime_get() { _runtime_http GET "$1" ""; }
+runtime_post() { _runtime_http POST "$1" "$2"; }
+runtime_put() { _runtime_http PUT "$1" "$2"; }
+
+# runtime_register <harness_version> [asset_types_json="[]"]
+# 0 = registrado (credenciales actualizadas) · 1 = fallo de red/parseo (fail-open, reintentable)
+# 2 = 409 incompatible_version (no reintentar sin actualizar el arnés)
+runtime_register() {
+  local hv="$1" asset_types="${2:-[]}" resp status frag
+  resp="$(runtime_post "/agents/register" "{\"harness_version\":\"$hv\",\"asset_types\":$asset_types}")"
+  status="$(runtime_http_status)"
+  case "$status" in
+    200)
+      command -v python3 >/dev/null 2>&1 || return 1
+      frag="$(python3 - "$resp" <<'PY'
+import json,sys
+try:
+    d=json.loads(sys.argv[1])
+    out={k:d.get(k) for k in ("agent_key","project_id","poll_interval_s","lease_ttl_s","manifest_hash") if k in d}
+    print(json.dumps(out))
+except Exception:
+    print("{}")
+PY
+)"
+      runtime_credentials_merge "$frag" || return 1
+      return 0
+      ;;
+    409)
+      echo "⛔ runtime_register: versión del arnés incompatible con el runtime — $resp" >&2
+      return 2
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+runtime_lock_path() {
+  echo "$(config_root)/.claude/state/context.lock"
+}
+
+runtime_lock_manifest_hash() {
+  local file; file="$(runtime_lock_path)"
+  [ -f "$file" ] || { echo ""; return; }
+  command -v python3 >/dev/null 2>&1 || { echo ""; return; }
+  python3 - "$file" <<'PY' 2>/dev/null
+import json,sys
+try:
+    print(json.load(open(sys.argv[1])).get("manifest_hash",""))
+except Exception:
+    print("")
+PY
+}
+
+# runtime_lock_write <manifest_hash> [files_json="[]"]
+runtime_lock_write() {
+  local hash="$1" files="${2:-[]}" file dir
+  file="$(runtime_lock_path)"; dir="$(dirname "$file")"
+  mkdir -p "$dir"
+  command -v python3 >/dev/null 2>&1 || return 1
+  python3 - "$file" "$hash" "$files" <<'PY' 2>/dev/null || return 1
+import json,sys,os,tempfile,datetime
+path,h,files=sys.argv[1],sys.argv[2],sys.argv[3]
+d={"manifest_hash":h,
+   "synced_at":datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+   "files":json.loads(files)}
+dirn=os.path.dirname(path) or "."
+fd,tmp=tempfile.mkstemp(dir=dirn,prefix=".context.lock.",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_projection_path() {
+  echo "$(config_root)/.claude/state/runtime-projection.json"
+}
+
+runtime_projection_read() {
+  local file; file="$(runtime_projection_path)"
+  [ -f "$file" ] || { echo "{}"; return; }
+  command -v python3 >/dev/null 2>&1 || { echo "{}"; return; }
+  python3 - "$file" <<'PY' 2>/dev/null
+import json,sys
+try:
+    d=json.load(open(sys.argv[1]))
+    print(json.dumps(d))
+except Exception:
+    print("{}")
+PY
+}
+
+runtime_projection_write() {
+  local body="$1" file dir
+  file="$(runtime_projection_path)"; dir="$(dirname "$file")"
+  mkdir -p "$dir"
+  command -v python3 >/dev/null 2>&1 || return 1
+  python3 - "$file" "$body" <<'PY' 2>/dev/null || return 1
+import json,sys,os,tempfile
+path,body=sys.argv[1],sys.argv[2]
+d=json.loads(body)
+dirn=os.path.dirname(path) or "."
+fd,tmp=tempfile.mkstemp(dir=dirn,prefix=".runtime-projection.",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_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:
+# perder un `slice_archived` o un `wiring_item_updated` dejaría la proyección del servidor
+# mintiendo. El volumen evictable es `progress_noted` (y su alias 0.10.x).
+# [#38] Los hechos máquina de proyecto viajan como UN solo tipo del catálogo v2
+# (`project_fact_updated`); los cinco alias legados (`scaffold_confirmed`,
+# `design_source_declared`, `project_kind_declared`, `foundation_declared`,
+# `harness_phase_changed`) ya no se encolan y salieron de la lista.
+# [#44] La lista lleva los NOMBRES DEL CATÁLOGO v2 del hub (event_catalog.SCHEMAS):
+# proteger de la evicción un tipo que el hub va a rechazar era absurdo. Salen
+# `branch_drift` y `front_integration_reported` (no existen en el catálogo; el despacho
+# los aparta a rejected/). Los tres alias 0.10.x del final (`checkpoint_created`,
+# `verdict_reported`, `escalation_raised`) siguen protegidos SOLO porque la capa de
+# compat del despacho los traduce y entrega — evictarlos perdería hechos entregables.
+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 checkpoint_created verdict_reported escalation_raised"
+
+runtime_outbox_dir() {
+  echo "$(config_root)/.claude/state/outbox"
+}
+
+# runtime_enqueue_event <type> <payload_json> [slice_id] — encola un evento con
+# client_event_id propio (idempotencia server-side) y aplica la cota tras encolar.
+# [EP-OR-08-B] `slice_id` es OPCIONAL y se escribe como clave de PRIMER NIVEL del evento
+# (no dentro de payload): `POST /events` lo exige por elemento para los tipos de ámbito
+# slice. Sin él, el evento se manda sin la clave — el ámbito proyecto la omite a propósito.
+runtime_enqueue_event() {
+  local type="$1" payload="$2" slice_id="${3:-}" dir
+  dir="$(runtime_outbox_dir)"; mkdir -p "$dir"
+  command -v python3 >/dev/null 2>&1 || return 1
+  python3 - "$dir" "$type" "$payload" "$slice_id" <<'PY' 2>/dev/null || return 1
+import json,sys,os,tempfile,uuid,datetime
+dir_,typ,payload,slice_id=sys.argv[1],sys.argv[2],sys.argv[3],sys.argv[4]
+cid=str(uuid.uuid4())
+ts=datetime.datetime.now(datetime.timezone.utc)
+d={"client_event_id":cid,"type":typ,"payload":json.loads(payload),
+   "enqueued_at":ts.strftime("%Y-%m-%dT%H:%M:%S.%fZ")}
+if slice_id:
+    d["slice_id"]=slice_id
+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
+PY
+  runtime_outbox_enforce_cap >/dev/null
+}
+
+# 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]
+# (TelemetryGap: {dropped>=1, window_h>0, reason<=2000}; extra="forbid" — el
+# {dropped_count, dropped_types} de 0.10.x era rechazo garantizado): `dropped` es el
+# conteo, `window_h` la ventana de la cota en horas y `reason` el motivo con los tipos
+# descartados. Imprime en stdout el conteo de descartados (última línea).
+runtime_outbox_enforce_cap() {
+  local dir; dir="$(runtime_outbox_dir)"
+  [ -d "$dir" ] || { echo 0; return 0; }
+  command -v python3 >/dev/null 2>&1 || { echo 0; return 0; }
+  python3 - "$dir" "$RUNTIME_OUTBOX_MAX_BYTES" "$RUNTIME_OUTBOX_MAX_AGE_S" "$RUNTIME_OUTBOX_PROTECTED" <<'PY' 2>/dev/null
+import json,os,sys,time,tempfile,uuid,datetime
+dir_,max_bytes,max_age,protected=sys.argv[1],int(sys.argv[2]),int(sys.argv[3]),set(sys.argv[4].split())
+files=[]
+total=0
+now=time.time()
+for name in os.listdir(dir_):
+    if not name.endswith(".json") or name.startswith("."):
+        continue
+    p=os.path.join(dir_,name)
+    try:
+        st=os.stat(p)
+        d=json.load(open(p))
+    except Exception:
+        continue
+    files.append((st.st_mtime,p,d.get("type","")))
+    total+=st.st_size
+files.sort()
+dropped=[]
+over_size=total>max_bytes
+for mtime,p,typ in files:
+    over_age=(now-mtime)>max_age
+    if not (over_size or over_age):
+        break
+    if typ in protected:
+        continue
+    try:
+        sz=os.path.getsize(p)
+        os.unlink(p)
+        total-=sz
+        dropped.append(typ)
+    except OSError:
+        pass
+    over_size=total>max_bytes
+if dropped:
+    # Coalescer en un telemetry_gap YA en cola (no despachado) en vez de acumular uno
+    # por descarte: telemetry_gap es protegido (nunca se evicta), así que sin coalescer
+    # crece sin límite mientras la cola siga sobre la cota.
+    existing_gap_path=None
+    existing_gap=None
+    for name in os.listdir(dir_):
+        if not name.endswith(".json") or name.startswith("."):
+            continue
+        p=os.path.join(dir_,name)
+        try:
+            d=json.load(open(p))
+        except Exception:
+            continue
+        if d.get("type")=="telemetry_gap":
+            existing_gap_path=p
+            existing_gap=d
+            break
+    window_h=max_age/3600.0
+    def resumen(tipos):
+        counts={}
+        for t in tipos:
+            k=t or "desconocido"
+            counts[k]=counts.get(k,0)+1
+        return ", ".join("%s x%d" % kv for kv in sorted(counts.items()))
+    encabezado="evicción por cota de la outbox (%d bytes / %.0f h)" % (max_bytes, window_h)
+    if existing_gap_path:
+        payload=existing_gap.get("payload") or {}
+        # Compat 0.10.x: un gap ya encolado puede traer {dropped_count, dropped_types};
+        # se normaliza aquí al payload del catálogo antes de acumular.
+        prev_n=payload.get("dropped", payload.get("dropped_count", 0)) or 0
+        prev_types=payload.get("dropped_types") or []
+        prev_reason=payload.get("reason") if isinstance(payload.get("reason"),str) else ""
+        base=prev_reason or (("%s: %s" % (encabezado, resumen(prev_types))) if prev_types else "")
+        texto=("%s; %s" % (base, resumen(dropped))) if base else ("%s: %s" % (encabezado, resumen(dropped)))
+        gap=existing_gap
+        gap["payload"]={"dropped": prev_n+len(dropped), "window_h": window_h, "reason": texto[:2000]}
+        fname=existing_gap_path
+        fd,tmp=tempfile.mkstemp(dir=dir_,prefix=".outbox.",suffix=".tmp")
+    else:
+        cid=str(uuid.uuid4())
+        ts=datetime.datetime.now(datetime.timezone.utc)
+        gap={"client_event_id":cid,"type":"telemetry_gap",
+             "payload":{"dropped":len(dropped),"window_h":window_h,
+                        "reason":("%s: %s" % (encabezado, resumen(dropped)))[:2000]},
+             "enqueued_at":ts.strftime("%Y-%m-%dT%H:%M:%S.%fZ")}
+        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(gap,out,indent=2,ensure_ascii=False)
+        os.replace(tmp,fname)
+    except Exception:
+        # No re-lanzar: la evicción YA tuvo éxito: fallar aquí no debe ocultar ese
+        # resultado ni romper el contrato de stdout (print(len(dropped)) siempre corre).
+        try: os.unlink(tmp)
+        except OSError: pass
+print(len(dropped))
+PY
+}
+
+RUNTIME_OUTBOX_BACKOFF_SCHEDULE="1 5 30 300"
+
+# runtime_dispatch_outbox — 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() {
+  local mode; mode="$(runtime_mode)"
+  [ "$mode" = "legacy" ] && return 0
+
+  command -v python3 >/dev/null 2>&1 || return 1
+
+  local dir; dir="$(runtime_outbox_dir)"
+  [ -d "$dir" ] || return 0
+
+  local state_file="$dir/.dispatch-state.json"
+  local now next_ok=0 attempt=0
+  now="$(date +%s)"
+  if [ -f "$state_file" ]; then
+    next_ok="$(python3 -c "import json;print(json.load(open('$state_file')).get('next_attempt_epoch',0))" 2>/dev/null || echo 0)"
+    attempt="$(python3 -c "import json;print(json.load(open('$state_file')).get('attempt',0))" 2>/dev/null || echo 0)"
+  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
+
+  # [#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`
+  # (`EventIn`); la clave interna de la outbox sigue siendo `type` y se traduce AQUÍ, al
+  # armar el cuerpo: los ficheros ya encolados en consumidores (0.10.x, clave `type`)
+  # drenan sin migración y el formato en disco no cambia (lo leen otros clientes).
+  # [#44] En este MISMO punto de salida vive la capa de compat de nombres/payloads: los
+  # productores ya encolan los nombres del catálogo v2, pero un consumidor 0.10.x dejó
+  # ficheros con los nombres viejos (`verdict_reported`, `checkpoint_created`,
+  # `escalation_raised`, `progress_note_recorded`) y payloads que `extra="forbid"`
+  # rechazaría — se traducen tipo Y claves al armar el cuerpo. Los tipos SIN equivalente
+  # en el catálogo (`tool_use_recorded`, `branch_drift`, `front_integration_reported`) se
+  # apartan localmente a rejected/ sin gastar red: mandarlos era rechazo garantizado.
+  local batch
+  batch="$(python3 - "$dir/rejected" "${files[@]}" <<'PY'
+import json,sys,os
+rejected_dir=sys.argv[1]
+SIN_EQUIVALENTE={"tool_use_recorded","branch_drift","front_integration_reported"}
+def traducir(t,p,slice_id):
+    p=dict(p)
+    if t=="verdict_reported":
+        # Un veredicto de RELEASE 0.10.x (payload con release_line, sin slice) no tiene
+        # camino por /events: se deja pasar tal cual y el hub lo rechaza con razón — la
+        # forma de slice se traduce a gate_verdict {gate, verdict, evidence…}.
+        t="gate_verdict"
+        if "status" in p and "verdict" not in p:
+            p["verdict"]=p.pop("status")
+        v=p.get("verdict")
+        if isinstance(v,str) and v.lower() in ("pass","fail"):
+            p["verdict"]=v.upper()
+        p={k:v for k,v in p.items() if k in ("gate","verdict","evidence","cause","details_ref")}
+    elif t=="checkpoint_created":
+        t="checkpoint_recorded"
+        if "note" in p and "summary" not in p:
+            p["summary"]=p.pop("note")
+        sid=p.pop("slice_id",None)
+        if sid and not slice_id:
+            slice_id=sid
+        p={k:v for k,v in p.items() if k in ("branch","commit_sha","summary")}
+    elif t=="escalation_raised":
+        t="slice_escalated"
+        pref=""
+        if p.get("gate"): pref+="[gate: %s] " % p["gate"]
+        if p.get("phase"): pref+="[fase: %s] " % p["phase"]
+        cause=p.get("cause") or (pref+str(p.get("reason") or ""))
+        p={"cause": (cause.strip() or "escalada sin causa registrada")[:2000]}
+    elif t=="progress_note_recorded":
+        t="progress_noted"
+        p={k:v for k,v in p.items() if k=="note"}
+    elif t in ("slice_submitted","slice_archived"):
+        p={}  # el catálogo no admite ningún campo (extra="forbid")
+    elif t=="wiring_checklist_seeded":
+        items=[]
+        for it in p.get("items") or []:
+            if isinstance(it,dict) and it.get("item_id"):
+                items.append({"item_id":it["item_id"],"kind":it.get("kind") or "","ref":it.get("ref") or ""})
+        p={"items":items}
+    elif t=="telemetry_gap" and "dropped" not in p and "dropped_count" in p:
+        tipos=p.get("dropped_types") or []
+        p={"dropped":p.get("dropped_count") or 0,"window_h":72.0,
+           "reason":("evicción por cota de la outbox del cliente; tipos descartados: "
+                     +", ".join(str(x) for x in tipos))[:2000]}
+    return t,p,slice_id
+items=[]
+for path in sys.argv[2:]:
+    try:
+        d=json.load(open(path))
+    except Exception:
+        continue
+    t=d.get("event_type") or d.get("type") or ""
+    if t in SIN_EQUIVALENTE:
+        try:
+            os.makedirs(rejected_dir,exist_ok=True)
+            os.replace(path,os.path.join(rejected_dir,os.path.basename(path)))
+            print("⚠ %r no existe en el catálogo v2 del hub: apartado a rejected/, no se enviará (issue #44)"
+                  % t, file=sys.stderr)
+        except OSError:
+            pass
+        continue
+    t,p,slice_id=traducir(t,d.get("payload") or {},d.get("slice_id"))
+    ev={"client_event_id": d.get("client_event_id") or "",
+        "event_type": t,
+        "payload": p}
+    if slice_id:
+        ev["slice_id"]=slice_id
+    items.append(ev)
+print(json.dumps({"events": items}, ensure_ascii=False))
+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)"
+  if [ "$n_items" = "0" ]; then
+    rm -f "$state_file"
+    return 0
+  fi
+
+  local resp status
+  resp="$(runtime_post "/events" "$batch")"
+  status="$(runtime_http_status)"
+
+  if [ "$status" = "200" ]; then
+    # [#37] Ack REAL del hub: {accepted:[cid], duplicates:[cid], rejected:[{client_event_id,
+    # reason}]}. Se conserva la lectura de la forma antigua {"results":[…]} (stubs/beta).
+    # Aceptado o duplicado => entregado, se borra. Rechazado POR ELEMENTO (fuera de catálogo
+    # o payload inválido) => reenviarlo es inútil: se aparta a rejected/ con su razón en
+    # stderr. Sin mención => se conserva para el próximo despacho (nunca se asume aceptado
+    # en silencio: perder un checkpoint/verdict/submit sin confirmación real viola la cota).
+    python3 - "$resp" "$dir/rejected" "${files[@]}" <<'PY'
+import json,sys,os
+resp=json.loads(sys.argv[1])
+rejected_dir=sys.argv[2]
+paths=sys.argv[3:]
+status={}
+reasons={}
+if isinstance(resp,dict) and "results" in resp:
+    for r in resp.get("results") or []:
+        status[r.get("client_event_id")]=r.get("status")
+elif isinstance(resp,dict):
+    for cid in resp.get("accepted") or []:
+        status[cid]="accepted"
+    for cid in resp.get("duplicates") or []:
+        status[cid]="accepted"
+    for r in resp.get("rejected") or []:
+        cid=r.get("client_event_id")
+        status[cid]="rejected"
+        reasons[cid]=r.get("reason") or "sin razón"
+for p in paths:
+    try:
+        cid=json.load(open(p)).get("client_event_id")
+    except Exception:
+        continue
+    st=status.get(cid)
+    if st=="accepted":
+        try: os.unlink(p)
+        except OSError: pass
+    elif st=="rejected":
+        print("⚠ el hub rechazó el evento %s: %s — apartado a rejected/, no se reenviará"
+              % (cid, reasons.get(cid,"sin razón")), file=sys.stderr)
+        try:
+            os.makedirs(rejected_dir,exist_ok=True)
+            os.replace(p, os.path.join(rejected_dir, os.path.basename(p)))
+        except OSError:
+            pass
+PY
+    rm -f "$state_file"
+    return 0
+  fi
+
+  # [#37] Un 4xx del LOTE (salvo 408/429) es un rechazo del contrato, no red caída:
+  # reintentarlo para siempre solo repite el mismo error y el usuario cree que reportó.
+  # Se loggea el cuerpo, el lote entero se aparta a rejected/ y NO se agenda backoff.
+  # 408 (timeout) y 429 (rate-limit) siguen siendo transitorios, igual que 5xx y 000.
+  case "$status" in
+    408|429) : ;;
+    4*)
+      local rejected_dir f
+      rejected_dir="$dir/rejected"
+      mkdir -p "$rejected_dir"
+      echo "⛔ el hub rechazó el lote de eventos (HTTP $status): $resp" >&2
+      echo "  ${#files[@]} evento(s) movidos a $rejected_dir/ — NO se reintentarán." >&2
+      echo "  Revisa el contrato del cliente (docs/runtime/protocolo-cliente-runtime.md) o" >&2
+      echo "  actualiza el arnés; el trabajo local sigue (fail-open)." >&2
+      for f in "${files[@]}"; do
+        mv "$f" "$rejected_dir/" 2>/dev/null
+      done
+      rm -f "$state_file"
+      return 1
+      ;;
+  esac
+
+  local schedule idx max_idx delay
+  read -ra schedule <<< "$RUNTIME_OUTBOX_BACKOFF_SCHEDULE"
+  idx=$attempt
+  max_idx=$(( ${#schedule[@]} - 1 ))
+  [ "$idx" -gt "$max_idx" ] && idx=$max_idx
+  delay="${schedule[$idx]}"
+  python3 -c "import json; json.dump({'next_attempt_epoch': $now + $delay, 'attempt': $((attempt + 1))}, open('$state_file','w'))"
+  return 1
+}