@trycore/spec-build-harness 0.8.4 → 0.10.0

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

@@ -0,0 +1,465 @@
+#!/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 sigue siendo `tool_use_recorded` y `progress_note_recorded`.
+RUNTIME_OUTBOX_PROTECTED="checkpoint_created verdict_reported slice_submitted handoff_recorded telemetry_gap branch_drift slice_archived wiring_checklist_seeded wiring_item_updated escalation_raised scaffold_confirmed design_source_declared project_kind_declared foundation_declared harness_phase_changed front_integration_reported"
+
+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 checkpoint/verdict/submit/handoff/telemetry_gap/
+# branch_drift. Si hubo descartes, encola un telemetry_gap describiéndolos. 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
+    if existing_gap_path:
+        payload=existing_gap.get("payload") or {}
+        payload["dropped_count"]=payload.get("dropped_count",0)+len(dropped)
+        payload["dropped_types"]=payload.get("dropped_types",[])+dropped
+        gap=existing_gap
+        gap["payload"]=payload
+        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_count":len(dropped),"dropped_types":dropped},
+             "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
+
+  local batch
+  batch="$(python3 - "${files[@]}" <<'PY'
+import json,sys
+items=[]
+for p in sys.argv[1:]:
+    try: items.append(json.load(open(p)))
+    except Exception: pass
+print(json.dumps(items))
+PY
+)"
+
+  local resp status
+  resp="$(runtime_post "/events" "$batch")"
+  status="$(runtime_http_status)"
+
+  if [ "$status" = "200" ]; then
+    python3 - "$resp" "${files[@]}" <<'PY'
+import json,sys,os
+resp=json.loads(sys.argv[1])
+paths=sys.argv[2:]
+results={r.get("client_event_id"):r.get("status") for r in resp.get("results",[])}
+for p in paths:
+    try:
+        cid=json.load(open(p)).get("client_event_id")
+    except Exception:
+        continue
+    # Sin mención en `results` => se conserva para el próximo despacho (nunca se asume
+    # aceptado en silencio: perder un checkpoint/verdict/submit sin confirmación real
+    # viola el contrato de la cota, Task 8).
+    st=results.get(cid)
+    if st in ("accepted","rejected"):
+        try: os.unlink(p)
+        except OSError: pass
+PY
+    rm -f "$state_file"
+    return 0
+  fi
+
+  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
+}

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

@@ -0,0 +1,221 @@
+#!/usr/bin/env bash
+# runtime-ops.sh — base común de las OPERACIONES DE DOMINIO que conducen las skills
+# [EP-OR-08-C]. Los hooks (sub-slice B) observan; esto transiciona: claim, veredictos,
+# checkpoints, submit, archive y hechos de proyecto. Lo usan hooks/build/slice-ops.sh y
+# hooks/build/release-ops.sh, que son INVOCADOS por las skills (no hooks registrados).
+#
+# Aquí vive el ÚNICO sitio del cliente bash donde se escriben rutas del runtime: si el
+# re-volcado de OpenAPI (EP-OR-13) mueve un endpoint, se toca este fichero y nada más.
+#
+# Diseño fail-open, igual que runtime-client.sh: ninguna función lanza; ante red caída,
+# python3 ausente o JSON corrupto se degrada a un valor seguro o a un rc distinguible.
+
+source "$(dirname "${BASH_SOURCE[0]}")/projection.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/agent-context.sh"
+
+# ── Códigos de salida (contrato con las skills; la prosa ramifica sobre estos números) ──
+OPS_RC_OK=0
+OPS_RC_USAGE=2
+OPS_RC_LEGACY=3
+OPS_RC_NO_SLICE=4
+OPS_RC_OFFLINE=5
+OPS_RC_REJECTED=6
+OPS_RC_NO_WORK=7
+
+# Tope de texto libre que el cliente manda al servidor (evidencias, notas): el protocolo §8
+# dice que el servidor rechaza payloads sobredimensionados; se trunca aquí, marcándolo.
+OPS_MAX_TEXT=4000
+
+# Gates canónicos (se validan en el cliente: un nombre inventado por el modelo no llega
+# a la red — compuerta mecánica barata, sin round-trip).
+OPS_SLICE_GATES="dor coherence_link tdd journey_smoke fidelity api data wiring_verified dod"
+OPS_RELEASE_GATES="security smell ux coherence stack_arch integration"
+
+# ── Tabla de rutas ──
+OPS_PATH_CLAIM="/tasks/next"
+OPS_PATH_CHECKPOINTS="/checkpoints"
+ops_path_verdicts() { echo "/slices/$1/verdicts"; }
+ops_path_submit() { echo "/slices/$1/submit"; }
+ops_path_release_verdicts() { echo "/releases/$1/verdicts"; }
+ops_path_front_integration() { echo "/fronts/$1/members/$2/integration"; }
+ops_path_mirror() { echo "/projects/$1/mirror/transitions"; }
+ops_path_proposals() { echo "/projects/$1/context/agent-proposals"; }
+
+ops_mode() { runtime_mode; }
+
+# ops_slice_id — id del slice activo según la caché de proyección ("" si no hay).
+ops_slice_id() { projection_get active_slice.slice_id ""; }
+
+# ops_urlenc <texto> — percent-encoding para segmentos de ruta (una línea de release puede
+# llevar espacios o barras). Sin python3 devuelve el texto tal cual: peor URL, nunca excepción.
+ops_urlenc() {
+  command -v python3 >/dev/null 2>&1 || { printf '%s' "$1"; return; }
+  printf '%s' "$1" | python3 -c 'import sys,urllib.parse; sys.stdout.write(urllib.parse.quote(sys.stdin.read(), safe=""))' 2>/dev/null || printf '%s' "$1"
+}
+
+# ops_json_str <texto> — imprime el texto como cadena JSON (comillas incluidas). El texto
+# viaja por STDIN, nunca por argv: así ni ARG_MAX ni el quoting de bash lo limitan.
+ops_json_str() {
+  command -v python3 >/dev/null 2>&1 || { printf '""'; return; }
+  printf '%s' "$1" | python3 -c 'import json,sys; sys.stdout.write(json.dumps(sys.stdin.read(), ensure_ascii=False))' 2>/dev/null || printf '""'
+}
+
+# ops_json_str_file <fichero> [max=OPS_MAX_TEXT] — igual, leyendo de un fichero y truncando
+# al tope (marcado en el propio texto para que el servidor y el humano lo vean).
+ops_json_str_file() {
+  local f="$1" max="${2:-$OPS_MAX_TEXT}"
+  [ -f "$f" ] || { printf '""'; return; }
+  command -v python3 >/dev/null 2>&1 || { printf '""'; return; }
+  python3 - "$f" "$max" <<'PY' 2>/dev/null || printf '""'
+import json,sys
+try:
+    t=open(sys.argv[1], encoding="utf-8", errors="replace").read()
+except Exception:
+    t=""
+m=int(sys.argv[2])
+if len(t) > m:
+    t = t[:m] + "\n…[truncado por el cliente]"
+sys.stdout.write(json.dumps(t, ensure_ascii=False))
+PY
+}
+
+# ops_tmpjson <json> — materializa un JSON en un fichero temporal e imprime su ruta.
+# Los payloads viajan a python3 y a curl POR FICHERO (regla dura del repo: nunca por argv).
+ops_tmpjson() {
+  local f
+  f="$(mktemp)" || return 1
+  printf '%s' "$1" > "$f"
+  echo "$f"
+}
+
+# ops_context_hashes — sha256 EFECTIVO local de cada archivo gobernado del lock
+# (protocolo §3 regla 3: el servidor detecta drift/manipulación local comparándolos con los
+# suyos). Se hashea el fichero real, NUNCA se repite el sha del lock: repetirlo convertiría
+# el reporte en un espejo del servidor y el drift sería indetectable. Fichero ausente => null.
+ops_context_hashes() {
+  local lock root
+  lock="$(runtime_lock_path)"
+  root="$(config_root)"
+  command -v python3 >/dev/null 2>&1 || { echo "[]"; return; }
+  python3 - "$lock" "$root" <<'PY' 2>/dev/null || echo "[]"
+import json,sys,os,hashlib
+lock,root=sys.argv[1],sys.argv[2]
+try:
+    files=json.load(open(lock)).get("files") or []
+except Exception:
+    files=[]
+out=[]
+for f in files:
+    if not isinstance(f,dict):
+        continue
+    p=f.get("path")
+    if not isinstance(p,str) or not p:
+        continue
+    full=os.path.join(root,".claude",p)
+    sha=None
+    try:
+        h=hashlib.sha256()
+        with open(full,"rb") as fh:
+            for chunk in iter(lambda: fh.read(65536), b""):
+                h.update(chunk)
+        sha=h.hexdigest()
+    except Exception:
+        sha=None
+    out.append({"path":p,"sha256":sha})
+print(json.dumps(out,ensure_ascii=False))
+PY
+}
+
+# ops_local_slice_ref — identidad del slice según el FICHERO local. Solo tiene sentido en
+# modo `dual`, donde el fichero es primario y el runtime crea la identidad por el mismo
+# camino que el import (spec §4.1-D). En `runtime` no se usa: allí manda la caché.
+# Imprime {} si no hay fichero, no hay python3 o no hay slice activo — nunca lanza.
+ops_local_slice_ref() {
+  local p
+  p="$(config_root)/.claude/state/build-state.json"
+  [ -f "$p" ] || { echo "{}"; return; }
+  command -v python3 >/dev/null 2>&1 || { echo "{}"; return; }
+  python3 - "$p" <<'PY' 2>/dev/null || echo "{}"
+import json,sys
+try:
+    d=json.load(open(sys.argv[1]))
+    s=d.get("active_slice") or {}
+except Exception:
+    s={}
+print(json.dumps({"epic_code": s.get("epica"),
+                  "openspec_change": s.get("openspec_change"),
+                  "branch": s.get("branch"),
+                  "phase": s.get("phase")}, ensure_ascii=False))
+PY
+}
+
+# ops_enqueue_from_file <type> <payload_file> [slice_id] — encola un evento cuyo payload
+# puede ser grande (checklist de wiring, evidencia, contenido propuesto): el payload se lee
+# del FICHERO dentro de python3, así que no pasa por argv (a diferencia de
+# runtime_enqueue_event, que sigue sirviendo para payloads pequeños).
+ops_enqueue_from_file() {
+  local type="$1" pfile="$2" slice_id="${3:-}" dir
+  dir="$(runtime_outbox_dir)"
+  mkdir -p "$dir"
+  command -v python3 >/dev/null 2>&1 || return 1
+  python3 - "$dir" "$type" "$pfile" "$slice_id" <<'PY' 2>/dev/null || return 1
+import json,sys,os,tempfile,uuid,datetime
+dir_,typ,pfile,slice_id=sys.argv[1],sys.argv[2],sys.argv[3],sys.argv[4]
+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,"payload":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
+}
+
+# ops_mirror <kind> <payload_file> — ingesta espejo del modo `dual` (spec §4.1-D). El
+# fichero local sigue siendo primario: un rechazo del reducer NO bloquea el trabajo, queda
+# como discrepancia del comparador. rc 0 aceptado · 5 no se pudo (red) · 6 rechazado.
+ops_mirror() {
+  local kind="$1" pfile="$2" pid body resp status tmp
+  pid="$(runtime_field project_id)"
+  [ -n "$pid" ] || return 5
+  command -v python3 >/dev/null 2>&1 || return 5
+  tmp="$(mktemp)" || return 5
+  python3 - "$kind" "$pfile" > "$tmp" <<'PY' 2>/dev/null
+import json,sys,datetime
+kind,pfile=sys.argv[1],sys.argv[2]
+try:
+    payload=json.load(open(pfile))
+except Exception:
+    payload={}
+print(json.dumps({"kind":kind,"payload":payload,"origin":"mirror",
+                  "occurred_at":datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")},
+                 ensure_ascii=False))
+PY
+  body="$(cat "$tmp" 2>/dev/null)"
+  rm -f "$tmp"
+  [ -n "$body" ] || return 5
+  resp="$(runtime_post "$(ops_path_mirror "$pid")" "$body")"
+  status="$(runtime_http_status)"
+  case "$status" in
+    200|201|202) return 0 ;;
+    409|422)
+      echo "⚠ el espejo rechazó «${kind}»: $resp" >&2
+      echo "  (queda como discrepancia del comparador dual; el trabajo local NO se bloquea)" >&2
+      return 6 ;;
+    *) return 5 ;;
+  esac
+}