@trycore/spec-build-harness 0.14.2 → 0.16.0

package/hooks/build/slice-ops.sh

@@ -5,9 +5,10 @@
 #
 #   uso: slice-ops.sh <subcomando> [opciones]
 #   subcomandos IMPLEMENTADOS (13 del plan + phase, issue #52; + propose-epic/epic-status/
-#                epic-writeback, issue #62): mode | claim | next-step | phase | gate | submit |
-#                archive | wiring | progress | checkpoint | fact | propose-asset |
-#                propose-epic | epic-status | epic-writeback | status | escalate.
+#                epic-writeback, issue #62; + graph-sync/graph-sync-status, EP-OR-17):
+#                mode | claim | next-step | phase | gate | submit | archive | wiring |
+#                progress | checkpoint | fact | propose-asset | propose-epic | epic-status |
+#                epic-writeback | graph-sync | graph-sync-status | status | escalate.
 #
 # Contrato con la prosa: cada subcomando devuelve un código de salida tipado
 # (0 ok · 2 uso · 3 legacy · 4 sin slice · 5 offline · 6 rechazado · 7 sin trabajo) y
@@ -16,12 +17,20 @@
 set -uo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$HERE/lib/runtime-ops.sh"
+# [#74] `register` manda el mismo harness_version/asset_types que el arranque de sesión.
+source "$HERE/lib/harness-meta.sh"
 
 usage() {
   cat >&2 <<'USAGE'
 uso: slice-ops.sh <subcomando> [opciones]
 
   mode                                          imprime legacy|dual|runtime
+  register [--runtime-url U] [--force]          da de alta ESTE árbol como agente propio con
+                                                un token que el ADMIN emitió para él (el token
+                                                se pide por STDIN, nunca por argumento).
+                                                Obligatorio en un worktree antes de escribir:
+                                                sin él se opera con la identidad heredada del
+                                                clon principal.
   claim                                         reclama trabajo (solo modo runtime; el hub
                                                 reparte por orden de cola — no hay --epic)
   next-step                                     deriva la siguiente acción desde la caché
@@ -46,10 +55,16 @@ uso: slice-ops.sh <subcomando> [opciones]
   epic-writeback [--id P] [--file F]           escribe en epicas.md las épicas ya APROBADAS,
                                                 con el código que asignó el hub (F debe estar
                                                 bajo docs/03-backlog/: carve-out §9.2)
+  graph-sync --file epics.json [--dry-run]      propone al hub el re-sync del grafo desde los
+                                                docs de discovery (el humano aprueba; con
+                                                --dry-run solo enseña el bundle, sin enviar)
+  graph-sync-status [--id P]                    veredicto del re-sync (QUEUED|PROPOSED|
+                                                APPROVED|REJECTED con el motivo del ADMIN)
   status [--no-refresh]                         informe local del agente
   escalate «razón» | --file F [--gate G]        registra un bloqueo (la decisión es humana)
 
 códigos de salida: 0 ok · 2 uso · 3 legacy · 4 sin slice · 5 offline · 6 rechazado · 7 sin trabajo
+                   · 9 identidad heredada (este worktree no está dado de alta: `register`)
 USAGE
 }
 
@@ -72,6 +87,78 @@ except Exception:
 ' "$2" 2>/dev/null
 }
 
+# [EP-OR-17] Los motivos del 409 del claim, como los emite el hub DE VERDAD.
+#
+# Este `case` esperaba `drift`/`contention`/`context_unresolvable`/`cross_project` como valor de
+# `reason` en la RAÍZ de la respuesta. Ninguno de esos literales existe en el backend del hub:
+# un HTTPException de FastAPI anida SIEMPRE bajo `detail`, y los cuatro casos llegan como
+#   • drift de contexto  → detail dict con `manifest_hash` (el hash al que sincronizar)
+#   • contención         → detail str «contención con otra escritura del contexto: reintenta…»
+#   • contexto irresoluble → detail str «…no hay trabajo sin contexto declarado»
+#   • lease ajeno/expirado → detail str «El lease está expirado, es de otro agente o no existe…»
+# Todos caían en el `*)` y salían como rechazo duro: un drift —que se resuelve sincronizando y
+# reintentando— dejaba al agente sin claim y sin saber por qué. La clasificación por FORMA (el
+# dict con manifest_hash) manda sobre la clasificación por texto, que solo se usa donde el hub
+# construye el mensaje en un único sitio. Se conserva la lectura plana por compatibilidad.
+
+# _claim_409_kind <json> — clasifica el 409: drift|contention|context_unresolvable|
+# cross_project|"" (desconocido).
+_claim_409_kind() {
+  command -v python3 >/dev/null 2>&1 || { echo ""; return; }
+  printf '%s' "$1" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+except Exception:
+    print(""); raise SystemExit(0)
+if not isinstance(d,dict):
+    print(""); raise SystemExit(0)
+det=d.get("detail")
+# Compatibilidad: una instancia que sí nombrara el motivo en un campo manda sobre el texto.
+for fuente in (det if isinstance(det,dict) else {}, d):
+    marca=fuente.get("reason") or fuente.get("error")
+    if isinstance(marca,str) and marca:
+        print(marca); raise SystemExit(0)
+# El drift se reconoce por FORMA, no por texto: el borde del hub garantiza el `manifest_hash`
+# en el cuerpo precisamente para que el cliente sepa a qué contexto sincronizar.
+if isinstance(det,dict) and det.get("manifest_hash"):
+    print("drift"); raise SystemExit(0)
+texto=det if isinstance(det,str) else (det.get("message","") if isinstance(det,dict) else "")
+t=str(texto).lower()
+if "contenci" in t:
+    print("contention")
+elif "no hay trabajo sin contexto" in t:
+    print("context_unresolvable")
+elif "otro agente" in t or "otro proyecto" in t:
+    print("cross_project")
+else:
+    print("")
+' 2>/dev/null
+}
+
+# _claim_409_text <json> — el motivo del hub en prosa, para enseñárselo al humano sin volcarle
+# el JSON crudo encima. Cae al cuerpo entero si no hay nada mejor.
+_claim_409_text() {
+  command -v python3 >/dev/null 2>&1 || { printf '%s' "$1"; return; }
+  printf '%s' "$1" | python3 -c '
+import json,sys
+crudo=sys.stdin.read()
+try:
+    d=json.loads(crudo)
+except Exception:
+    print(crudo.strip()); raise SystemExit(0)
+if not isinstance(d,dict):
+    print(crudo.strip()); raise SystemExit(0)
+det=d.get("detail")
+if isinstance(det,str) and det:
+    print(det)
+elif isinstance(det,dict):
+    print(det.get("message") or json.dumps(det,ensure_ascii=False))
+else:
+    print(crudo.strip())
+' 2>/dev/null
+}
+
 # _claim_render <json> — resumen compacto del slice reclamado (lo lee el humano y el modelo).
 _claim_render() {
   command -v python3 >/dev/null 2>&1 || { echo "$1"; return; }
@@ -127,31 +214,33 @@ _claim_once() {
       echo "NO_WORK: el runtime no tiene trabajo disponible para este agente"
       return $OPS_RC_NO_WORK ;;
     409)
-      reason="$(_claim_field "$resp" reason)"
-      [ -n "$reason" ] || reason="$(_claim_field "$resp" error)"
+      # [EP-OR-17] El grafo rancio se comprueba ANTES del `case`, con el helper del cliente:
+      # conoce la forma REAL del hub (`detail.error = graph_version_stale`) además de la plana
+      # que este sitio leía a mano y que el hub no emite en ninguna parte.
+      local server_gv
+      if server_gv="$(runtime_stale_graph_version "$resp")"; then
+        # [#63] No es un error: es la señal de que operamos contra una foto vieja del
+        # backlog. Se anota el desfase (lo muestra `status`) y se pide UN reintento con la
+        # proyección refrescada. Mismo patrón que el 409 del lease en hb_renew.
+        runtime_graph_note_stale "$gv" "$server_gv"
+        echo "⚠ 409 (graph_version_stale): el grafo local (v${gv:-?}) va por detrás del hub (v${server_gv:-?})" >&2
+        return 21
+      fi
+      reason="$(_claim_409_kind "$resp")"
       case "$reason" in
-        stale_graph)
-          # [#63] No es un error: es la señal de que operamos contra una foto vieja del
-          # backlog. Se anota el desfase (lo muestra `status`) y se pide UN reintento con la
-          # proyección refrescada. Mismo patrón que el 409 del lease en hb_renew.
-          local server_gv
-          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"
-          echo "⚠ 409 (stale_graph): el grafo local (v${gv:-?}) va por detrás del hub (v${server_gv:-?})" >&2
-          return 21 ;;
         drift|contention)
-          echo "⚠ 409 ($reason): reintentable" >&2
+          echo "⚠ 409 ($reason): reintentable — $(_claim_409_text "$resp")" >&2
           return 20 ;;
         context_unresolvable)
-          echo "⛔ 409 contexto irresoluble — NO reintentar: $resp" >&2
+          echo "⛔ 409 contexto irresoluble — NO reintentar: $(_claim_409_text "$resp")" >&2
           echo "  Resuélvelo en el hub (propuesta → publicación) y vuelve a reclamar." >&2
           return $OPS_RC_REJECTED ;;
         cross_project)
-          echo "⛔ 409 cruce de proyecto (queda auditado en el servidor): $resp" >&2
+          echo "⛔ 409 cruce de proyecto (queda auditado en el servidor): $(_claim_409_text "$resp")" >&2
           echo "  Este clon está registrado contra otro proyecto: revisa runtime.credentials." >&2
           return $OPS_RC_REJECTED ;;
         *)
-          echo "⛔ 409 sin razón reconocida en el cuerpo: $resp" >&2
+          echo "⛔ 409 del hub: $(_claim_409_text "$resp")" >&2
           return $OPS_RC_REJECTED ;;
       esac ;;
     401|403)
@@ -322,11 +411,15 @@ cmd_fact() {
 # escribible, python3 ausente u otro fallo local) — el caller decide qué avisar y nunca debe
 # reportar éxito en ese caso (fail-open sobre el trabajo local, nunca sobre el reporte).
 _ops_emit_event() {
-  local tipo="$1" payload="$2" sid="${3:-}" pfile mode
+  local tipo="$1" payload="$2" sid="${3:-}" pfile mode epic
   mode="$(ops_mode)"
   pfile="$(ops_tmpjson "$payload")" || return $OPS_RC_OFFLINE
   if [ "$mode" = "dual" ]; then
-    ops_mirror "$tipo" "$pfile" || echo "⚠ «${tipo}» no espejado; el comparador dual lo marcará" >&2
+    # [EP-OR-17] El `epic_code` va en el SOBRE del espejo, que es donde el hub lo lee. Muchos de
+    # los tipos que pasan por aquí (hechos de proyecto, archivado, escalada) no son espejables:
+    # `ops_mirror` los corta en local con rc 8 antes de gastar una llamada.
+    epic="$(ops_local_slice_ref | python3 -c 'import json,sys; print(json.load(sys.stdin).get("epic_code") or "")' 2>/dev/null)"
+    ops_mirror "$tipo" "$pfile" "$epic" || echo "⚠ «${tipo}» no espejado; el comparador dual lo marcará" >&2
     rm -f "$pfile"
     return $OPS_RC_OK
   fi
@@ -945,6 +1038,294 @@ PY
   return $OPS_RC_OK
 }
 
+# ── graph-sync ───────────────────────────────────────────────────────────────────────
+# [EP-OR-17] Hasta ahora el grafo del hub dejaba de evolucionar tras el import inicial de
+# ADMIN: las épicas que discovery añadía después no tenían por dónde entrar, y TODOS los
+# eventos de un slice cuya épica no está en el grafo rebotan con «la épica no existe en el
+# grafo del proyecto». Este carril lo cierra sin regalarle al agente la potestad de mutar el
+# grafo: el arnés PROPONE el bundle, el hub calcula el delta y un humano aprueba en la consola.
+
+# _graph_sync_bundle <fichero-epics> [from_docs] — imprime el bundle proyectado al contrato,
+# o "" con rc 2 (no cumple el contrato) / rc 5 (falta infraestructura local).
+_graph_sync_bundle() {
+  local f="$1" docs="${2:-}" gb
+  gb="$HERE/../../scripts/lib/graph-bundle.py"
+  [ -f "$gb" ] || gb="$(config_root)/.claude/scripts/lib/graph-bundle.py"
+  if [ ! -f "$gb" ]; then
+    echo "⛔ no se encuentra graph-bundle.py: reinstala con \`trycore-build update\`" >&2
+    return $OPS_RC_OFFLINE
+  fi
+  # [Importante] Sin python3 no es "bundle inválido" (rc 2 de uso): es una degradación de
+  # infraestructura. Se anuncia con esas palabras para que no se confunda con un backlog mal
+  # escrito, que es lo que el agente iría a arreglar.
+  command -v python3 >/dev/null 2>&1 || {
+    echo "⛔ sin python3: no se puede construir el bundle en local" >&2
+    return $OPS_RC_OFFLINE
+  }
+  if [ -n "$docs" ]; then
+    python3 "$gb" --for-sync --from-docs "$docs" < "$f"
+  else
+    python3 "$gb" --for-sync < "$f"
+  fi
+}
+
+# _graph_sync_out <respuesta> <clave> — escalar de la respuesta del hub ("" si falta). Acepta
+# tanto el cuerpo desnudo como el sobre `{"response": …}` con el que el carril directo guarda
+# los acks, que es de donde lo lee este comando.
+_graph_sync_out() {
+  command -v python3 >/dev/null 2>&1 || { echo ""; return; }
+  printf '%s' "$1" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+    r=(d.get("response") if isinstance(d.get("response"),dict) else d) or {}
+    v=r.get(sys.argv[1])
+    print("" if v is None else (v if isinstance(v,str) else json.dumps(v,ensure_ascii=False)))
+except Exception:
+    print("")
+' "$2" 2>/dev/null
+}
+
+# _graph_sync_delta_render <delta-json> — resumen legible del delta que devuelve el hub. Es lo
+# que el humano va a aprobar: enseñarlo aquí evita que el agente proponga a ciegas.
+_graph_sync_delta_render() {
+  command -v python3 >/dev/null 2>&1 || return 0
+  printf '%s' "$1" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+except Exception:
+    raise SystemExit(0)
+if not isinstance(d,dict):
+    raise SystemExit(0)
+print("delta propuesto: %d épicas nuevas · %d épicas con cambios · %d historias nuevas · %d historias con cambios"
+      % (len(d.get("epics_added") or []), len(d.get("epics_changed") or []),
+         len(d.get("stories_added") or []), len(d.get("stories_changed") or [])))
+for e in (d.get("epics_added") or [])[:10]:
+    print("  + %s %s" % (e.get("code",""), e.get("title","")))
+for e in (d.get("epics_changed") or [])[:10]:
+    print("  ~ %s (%s)" % (e.get("code",""), ", ".join(sorted((e.get("fields") or {}).keys()))))
+' 2>/dev/null
+}
+
+cmd_graph_sync() {
+  local file="" docs="" dry=0 mode pid bundle rc cid pfile n_epicas
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --file) file="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --from-docs) docs="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --dry-run) dry=1; shift ;;
+      *) shift ;;
+    esac
+  done
+  if [ -z "$file" ]; then
+    echo "uso: slice-ops.sh graph-sync --file epics.json [--from-docs docs/03-backlog/epicas.md] [--dry-run]" >&2
+    echo "  epics.json: {\"epics\":[{code,title,layer,files_scope[],depends_on[],stories[]}]}" >&2
+    echo "  lo escribes leyendo docs/03-backlog/epicas.md y las HU-*.md (igual que en /build:onboard)." >&2
+    return $OPS_RC_USAGE
+  fi
+  [ -f "$file" ] || { echo "⛔ no existe el fichero de épicas: $file" >&2; return $OPS_RC_USAGE; }
+  [ -z "$docs" ] || [ -f "$docs" ] || { echo "⛔ no existe el documento de épicas: $docs" >&2; return $OPS_RC_USAGE; }
+
+  # El bundle se construye ANTES de mirar el modo: `--dry-run` tiene que servir también en
+  # legacy y dual, que es donde más falta hace revisar el grafo antes de registrarse.
+  bundle="$(_graph_sync_bundle "$file" "$docs")"
+  rc=$?
+  if [ $rc -ne 0 ] || [ -z "$bundle" ]; then
+    [ $rc -eq $OPS_RC_OFFLINE ] && return $OPS_RC_OFFLINE
+    echo "⛔ el bundle no se envía: corrige los docs de discovery y vuelve a intentarlo." >&2
+    return $OPS_RC_USAGE
+  fi
+  if [ "$dry" = 1 ]; then
+    printf '%s\n' "$bundle"
+    echo "--dry-run: nada se ha enviado. Quita la opción para proponer el re-sync al hub." >&2
+    return $OPS_RC_OK
+  fi
+
+  mode="$(ops_mode)"
+  if [ "$mode" != "runtime" ]; then
+    echo "${mode}: el re-sync del grafo solo opera en modo \`runtime\`."
+    echo "Con el fichero local como fuente de verdad, el grafo vive en los documentos y entra"
+    echo "al hub por el import de admin (\`/build:onboard\`). Usa --dry-run para revisarlo."
+    return $OPS_RC_LEGACY
+  fi
+  pid="$(runtime_field project_id)"
+  [ -n "$pid" ] || { echo "⛔ sin project_id en runtime.credentials: corre \`trycore-build init\`" >&2; return $OPS_RC_REJECTED; }
+
+  cid="$(ops_graph_sync_cid)"
+  # El cid es determinista, luego REUTILIZABLE: si el ledger se pierde o se limpia, el
+  # contador vuelve atrás y el rastro local de un envío anterior con ese mismo cid (su ack o
+  # su apartado) seguiría en disco. Leerlo haría que este comando reportara el resultado de
+  # una propuesta que NO acaba de enviar. Se retira antes de encolar: el hub sigue
+  # deduplicando por cid igualmente, así que borrar el rastro local no duplica nada.
+  rm -f "$(runtime_outbox_dir)/acks/${cid}.json" 2>/dev/null
+  rm -f "$(runtime_outbox_dir)/rejected/"*"${cid}.json" 2>/dev/null
+  pfile="$(ops_tmpjson "{\"bundle\":$bundle}")" || return $OPS_RC_OFFLINE
+  # El `1` pide el estampado de `graph_version` AL DESPACHAR: un re-sync que espera en la cola
+  # offline debe salir con la versión vigente en ese momento, no con la de ayer. El `$cid` fija
+  # la identidad: el reintento tras un 409 la reusa y el hub deduplica.
+  cid="$(runtime_enqueue_direct graph_sync_proposed POST "$(ops_path_graph_sync_proposals "$pid")" "$pfile" 1 "$cid")"
+  rm -f "$pfile"
+  if [ -z "$cid" ]; then
+    echo "⛔ no se pudo encolar el re-sync (outbox no escribible): reintenta." >&2
+    return $OPS_RC_OFFLINE
+  fi
+  n_epicas="$(printf '%s' "$bundle" | python3 -c 'import json,sys; print(len(json.load(sys.stdin)["epics"]))' 2>/dev/null || echo 0)"
+  ops_graph_sync_ledger_upsert "{\"client_event_id\":$(ops_json_str "$cid"),\"status\":\"QUEUED\",\"proposal_id\":null,\"epics\":$n_epicas}"
+
+  _graph_sync_despachar "$cid"
+}
+
+# _graph_sync_despachar <cid> — despacha, interpreta el resultado y, ante un grafo rancio,
+# refresca la proyección y reintenta UNA vez.
+#
+# El reintento vive AQUÍ y no en el despachador porque `runtime-client.sh` es agnóstico al
+# dominio: no sabe qué es un bundle ni cuándo vale la pena volver a intentarlo. Y re-estampar
+# con la versión nueva ES «recalcular el bundle contra la versión que devuelve el hub»: el
+# bundle no depende de la versión del grafo, solo el sello que lo acompaña.
+_graph_sync_despachar() {
+  local cid="$1" intento=1 ack reason id_prop delta
+  while :; do
+    runtime_dispatch_outbox >/dev/null 2>&1
+    ack="$(ops_epic_ack_read "$cid")"
+    if [ -n "$ack" ]; then
+      if [ "$(_graph_sync_out "$ack" empty_delta)" = "true" ]; then
+        # HU-OR-72 E2: no es un error ni una propuesta — el bundle coincide con el grafo
+        # vigente. Se cierra la entrada del ledger para que `graph-sync-status` no vaya a
+        # preguntar por una propuesta que el hub nunca creó.
+        ops_graph_sync_ledger_upsert "{\"client_event_id\":$(ops_json_str "$cid"),\"status\":\"EMPTY_DELTA\"}"
+        echo "el grafo del hub ya está al día: no hay cambios que proponer."
+        return $OPS_RC_OK
+      fi
+      id_prop="$(_graph_sync_out "$ack" id)"
+      delta="$(_graph_sync_out "$ack" delta)"
+      ops_graph_sync_ledger_upsert "{\"client_event_id\":$(ops_json_str "$cid"),\"status\":\"PROPOSED\",\"proposal_id\":$(ops_json_str "$id_prop")}"
+      echo "re-sync propuesto: ${id_prop:-sin identificador en la respuesta}"
+      [ -n "$delta" ] && _graph_sync_delta_render "$delta"
+      echo "Queda en PROPOSED: NADA se ha aplicado al grafo hasta que un humano lo apruebe en"
+      echo "la consola del hub. Sigue el veredicto con \`slice-ops.sh graph-sync-status\`."
+      return $OPS_RC_OK
+    fi
+    reason="$(ops_epic_rejected_reason "$cid")"
+    if [ -n "$reason" ]; then
+      ops_graph_sync_ledger_upsert "{\"client_event_id\":$(ops_json_str "$cid"),\"status\":\"FAILED\",\"reason\":$(ops_json_str "$reason")}"
+      case "$reason" in
+        *"HTTP 404"*|*404*)
+          # Anti-oráculo (HU-OR-72 E4): el hub responde lo MISMO para «no existe» y «no es
+          # tuyo». Afirmar una de las dos causas mandaría a buscar el problema equivocado.
+          echo "⛔ el hub respondió 404. Son dos causas indistinguibles POR DISEÑO: o el proyecto" >&2
+          echo "  no existe, o no es el tuyo (el hub no confirma cuál para no filtrar proyectos" >&2
+          echo "  ajenos). Verifica el project_id de runtime.credentials y que el hub tenga" >&2
+          echo "  la superficie de re-sync (EP-OR-17)." >&2 ;;
+        *) echo "⛔ el hub rechazó el re-sync: $reason" >&2 ;;
+      esac
+      return $OPS_RC_REJECTED
+    fi
+    # Sigue en la cola. Si fue por grafo rancio, el despachador dejó el marcador de desfase: se
+    # refresca la proyección y se reintenta UNA vez con la versión nueva.
+    if [ "$intento" = 1 ] && [ -n "$(runtime_graph_status_read)" ] && [ "$(runtime_graph_status_read)" != "{}" ]; then
+      intento=2
+      echo "⚠ el hub dice que nuestro grafo va rancio: se refresca el contexto y se reintenta una vez." >&2
+      agent_context_fetch_and_cache >/dev/null 2>&1 || \
+        echo "⚠ no se pudo refrescar /agent/context: el reintento sale con la versión que haya" >&2
+      # El despacho lleva mutex y estado de backoff: sin limpiarlo, el segundo intento cedería
+      # el turno y el reintento no ocurriría en este proceso.
+      rm -f "$(runtime_outbox_dir)/.dispatch-state.json" 2>/dev/null
+      continue
+    fi
+    echo "re-sync encolado: $cid"
+    echo "PENDIENTE: se despachará solo (el daemon de heartbeat lo lleva). Sin conexión aún, o el"
+    echo "daemon estaba drenando la cola en este instante. \`slice-ops.sh graph-sync-status\` lo sigue."
+    return $OPS_RC_OFFLINE
+  done
+}
+
+# ── graph-sync-status ────────────────────────────────────────────────────────────────
+# [EP-OR-17] El motivo del rechazo lo escribe el ADMIN precisamente para que lo lea la terminal
+# que propuso: sin este subcomando el veredicto humano se queda en la consola del hub y el
+# agente vuelve a proponer exactamente lo mismo. Informativo: rc 0 siempre en runtime, pase lo
+# que pase — es una consulta, y fallar aquí no arregla nada.
+cmd_graph_sync_status() {
+  local only="" mode pid entries n i cid pidv st resp status reason ack
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --id) only="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  mode="$(ops_mode)"
+  if [ "$mode" != "runtime" ]; then
+    echo "${mode}: no hay hub al que preguntar por el re-sync del grafo."
+    return $OPS_RC_LEGACY
+  fi
+  pid="$(runtime_field project_id)"
+  entries="$(ops_graph_sync_ledger_read)"
+  n="$(printf '%s' "$entries" | python3 -c 'import json,sys; print(len(json.load(sys.stdin).get("proposals") or []))' 2>/dev/null || echo 0)"
+  case "$n" in ''|*[!0-9]*) n=0 ;; esac
+  if [ "$n" = 0 ]; then
+    echo "no hay ninguna propuesta de re-sync registrada en esta terminal."
+    echo "Propón una con \`slice-ops.sh graph-sync --file epics.json\`."
+    return $OPS_RC_OK
+  fi
+  i=0
+  while [ "$i" -lt "$n" ]; do
+    cid="$(printf '%s' "$entries" | python3 -c 'import json,sys; print(json.load(sys.stdin)["proposals"][int(sys.argv[1])].get("client_event_id") or "")' "$i" 2>/dev/null)"
+    pidv="$(printf '%s' "$entries" | python3 -c 'import json,sys; print(json.load(sys.stdin)["proposals"][int(sys.argv[1])].get("proposal_id") or "")' "$i" 2>/dev/null)"
+    st="$(printf '%s' "$entries" | python3 -c 'import json,sys; print(json.load(sys.stdin)["proposals"][int(sys.argv[1])].get("status") or "")' "$i" 2>/dev/null)"
+    i=$((i + 1))
+    [ -z "$only" ] || [ "$only" = "$pidv" ] || [ "$only" = "$cid" ] || continue
+    if [ -z "$pidv" ]; then
+      # Todavía sin identificador del hub: el estado lo dicta el carril directo local, no la red.
+      ack="$(ops_epic_ack_read "$cid")"
+      reason="$(ops_epic_rejected_reason "$cid")"
+      if [ "$st" = "EMPTY_DELTA" ]; then
+        echo "$cid  EMPTY_DELTA  (el grafo ya estaba al día: el hub no creó ninguna propuesta)"
+      elif [ -n "$reason" ]; then
+        echo "$cid  FAILED  $reason"
+      elif [ -n "$ack" ]; then
+        echo "$cid  PROPOSED (ack recibido, sin identificador legible en la respuesta)"
+      else
+        echo "$cid  ${st:-QUEUED}  (pendiente de despacho: el daemon de heartbeat la lleva)"
+      fi
+      continue
+    fi
+    resp="$(runtime_get "$(ops_path_graph_sync_proposal "$pid" "$pidv")")"
+    status="$(runtime_http_status)"
+    case "$status" in
+      200) _graph_sync_status_render "$cid" "$pidv" "$resp" ;;
+      404)
+        # HU-OR-73 E5: «no existe» y «es de otro proyecto» son el MISMO cuerpo, bit a bit.
+        echo "$pidv  DESCONOCIDA para el hub (o es de otro proyecto: son indistinguibles)" ;;
+      *)
+        echo "$pidv  ${st:-?}  (el hub no respondió, HTTP $status: se muestra el último estado conocido)" ;;
+    esac
+  done
+  return $OPS_RC_OK
+}
+
+# _graph_sync_status_render <cid> <proposal_id> <respuesta> — pinta el veredicto y lo persiste
+# en el ledger. La persistencia va aquí y no en el llamador porque el estado del hub SOLO se
+# conoce al leer la respuesta: guardarlo fuera obligaría a re-parsearla.
+_graph_sync_status_render() {
+  local cid="$1" pidv="$2" resp="$3" st reason applied
+  st="$(_graph_sync_out "$resp" status)"
+  reason="$(_graph_sync_out "$resp" reject_reason)"
+  applied="$(_graph_sync_out "$resp" graph_version_applied)"
+  case "$st" in
+    APPROVED)
+      echo "$pidv  APPROVED  (grafo del hub en v${applied:-?})"
+      echo "         nada más que hacer: las historias nuevas entran solas al reparto del claim." ;;
+    REJECTED)
+      echo "$pidv  REJECTED  ${reason:-sin motivo registrado}"
+      echo "         corrige los docs de discovery y vuelve a proponer con \`graph-sync\`." ;;
+    PROPOSED)
+      echo "$pidv  PROPOSED  (esperando aprobación humana en la consola del hub)" ;;
+    *)
+      echo "$pidv  ${st:-?}" ;;
+  esac
+  ops_graph_sync_ledger_upsert "{\"client_event_id\":$(ops_json_str "$cid"),\"status\":$(ops_json_str "${st:-PROPOSED}"),\"reject_reason\":$(ops_json_str "$reason"),\"graph_version_applied\":$(ops_json_str "$applied")}"
+}
+
 # ── status ───────────────────────────────────────────────────────────────────────────
 # Informe local del agente: modo, proyecto (con sus hechos: scaffold/fuente de diseño/
 # tipo/caparazón — la precondición temprana de /build:slice y /build:work la evalúan de
@@ -959,6 +1340,16 @@ cmd_status() {
     esac
   done
   mode="$(ops_mode)"
+  # [#74] `status` conserva el fallback a propósito — es la herramienta de diagnóstico de un
+  # worktree que todavía no se dio de alta, y negarle la lectura lo dejaría a ciegas. Pero se
+  # dice en la primera línea de quién es el estado que está mirando: sin el banner, un informe
+  # heredado es indistinguible de uno propio, y es exactamente así como se llega a creer que
+  # se tiene un lease que en realidad es de otro agente.
+  if config_is_inherited_root; then
+    echo "identidad:    ⚠ HEREDADA del clon principal ($(config_main_clone_root)) — solo lectura"
+    echo "              lo de abajo es el estado de ESE agente, no del tuyo. Antes de reclamar"
+    echo "              o reportar: \`slice-ops.sh register\` con un token propio del ADMIN."
+  fi
   echo "modo:         $mode"
   if [ "$mode" = "legacy" ]; then
     echo "estado:       el fichero .claude/state/build-state.json es la fuente de verdad (v0.8.5)"
@@ -1118,30 +1509,22 @@ cmd_escalate() {
 }
 
 # ── Helpers comunes de los subcomandos que transicionan ──────────────────────────────
-# _ops_dual_mirror <kind> <payload_json> — en `dual` el fichero es primario: se añade la
-# identidad local al payload y se manda al espejo. Un fallo del espejo NUNCA bloquea:
-# se avisa y se devuelve 0 (queda como discrepancia del comparador, spec §6.1).
+# _ops_dual_mirror <event_type> <payload_json> — en `dual` el fichero es primario: la transición
+# se manda al espejo con el `epic_code` del estado local. Un fallo del espejo NUNCA bloquea: se
+# avisa y se devuelve 0 (queda como discrepancia del comparador, spec §6.1).
+#
+# [EP-OR-17] El `slice_ref` que se inyectaba DENTRO del payload se ha eliminado: los schemas del
+# catálogo son `extra="forbid"` y ese campo era rechazo garantizado. Su información —de qué
+# épica es la transición— es justamente el `epic_code` del SOBRE, que ahora sí viaja donde el
+# hub lo lee.
 _ops_dual_mirror() {
-  local kind="$1" payload="$2" ref pfile rc
-  ref="$(ops_local_slice_ref)"
+  local event_type="$1" payload="$2" epic pfile rc
+  epic="$(ops_local_slice_ref | python3 -c 'import json,sys; print(json.load(sys.stdin).get("epic_code") or "")' 2>/dev/null)"
   pfile="$(ops_tmpjson "$payload")" || return $OPS_RC_OK
-  command -v python3 >/dev/null 2>&1 && python3 - "$pfile" "$ref" <<'PY' 2>/dev/null
-import json,sys
-p,ref=sys.argv[1],sys.argv[2]
-try:
-    d=json.load(open(p))
-except Exception:
-    d={}
-try:
-    d["slice_ref"]=json.loads(ref)
-except Exception:
-    d["slice_ref"]={}
-json.dump(d,open(p,"w"),ensure_ascii=False)
-PY
-  ops_mirror "$kind" "$pfile"
+  ops_mirror "$event_type" "$pfile" "$epic"
   rc=$?
   rm -f "$pfile"
-  [ $rc -eq 0 ] || echo "⚠ transición «${kind}» no espejada (rc $rc): el comparador dual la marcará" >&2
+  [ $rc -eq 0 ] || echo "⚠ transición «${event_type}» no espejada (rc $rc): el comparador dual la marcará" >&2
   return $OPS_RC_OK
 }
 
@@ -1485,7 +1868,9 @@ PY
   fi
   mode="$(ops_mode)"
   if [ "$mode" = "dual" ]; then
-    ops_mirror wiring_checklist_seeded "$pfile" || echo "⚠ siembra de wiring no espejada; el comparador dual la marcará" >&2
+    ops_mirror wiring_checklist_seeded "$pfile" \
+      "$(ops_local_slice_ref | python3 -c 'import json,sys; print(json.load(sys.stdin).get("epic_code") or "")' 2>/dev/null)" \
+      || echo "⚠ siembra de wiring no espejada; el comparador dual la marcará" >&2
     rm -f "$pfile"
     return $OPS_RC_OK
   fi
@@ -1613,10 +1998,197 @@ cmd_checkpoint() {
   _ops_post_or_queue "$OPS_PATH_CHECKPOINTS" "$payload" checkpoint_recorded "$sid" "el checkpoint" "$queue_payload"
 }
 
+# ── register ─────────────────────────────────────────────────────────────────────────
+# [#74] Alta EXPLÍCITA de este árbol de trabajo como agente propio.
+#
+# El caso que lo motiva: dos agentes construyendo dos épicas en la misma máquina, cada uno en
+# su worktree. El hub reparte las dos sin objeción — el bloqueo estaba aquí: un worktree sin
+# `.claude/state/runtime.credentials` propio hereda el del clon principal por el fallback de
+# `config_root()` y trabaja con SU identidad sin decirlo.
+#
+# Tres decisiones de diseño que no son gratuitas:
+#   1. El token entra por STDIN (prompt si hay TTY), jamás por argumento: un `--token` queda
+#      en el historial del shell y en `ps`. Por eso `register` es un comando de terminal
+#      humano y NO se invoca desde dentro de un claim — los hooks y las tool calls no tienen
+#      TTY y un `read` ahí colgaría la llamada.
+#   2. Se siembra PRIMERO el fichero local, para que `config_root()` ancle en este árbol antes
+#      de cualquier merge. Al revés, `runtime_register` habría hecho upsert del token nuevo
+#      sobre el fichero del clon principal, pisándole la identidad al agente que trabaja ahí.
+#   3. Se valida que el `agent_key` obtenido DIFIERA del que tiene el principal. El hub no crea
+#      identidades en `/agents/register`: el `agent_key` es el `agent_id` que el ADMIN grabó en
+#      el token al emitirlo. Mismo token ⇒ mismo agente ⇒ el claim devolvería el trabajo del
+#      otro worktree. Un token por agente, siempre.
+#
+# Ante cualquier fallo se revierte: o el árbol queda con identidad propia y verificada, o
+# queda exactamente como estaba. Un fichero de credenciales a medias es peor que ninguno.
+
+# _reg_rollback <fichero> <backup> — deja el fichero local como estaba antes de `register`.
+_reg_rollback() {
+  local file="$1" backup="$2"
+  if [ -n "$backup" ] && [ -f "$backup" ]; then
+    cp "$backup" "$file" 2>/dev/null
+    rm -f "$backup"
+  else
+    rm -f "$file"
+  fi
+}
+
+cmd_register() {
+  local url="" force=0 wt main localfile mainfile mainkey newkey token backup="" hv at rc
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --runtime-url) url="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --force) force=1; shift ;;
+      --token|--project-token|--runtime-token)
+        echo "⛔ el token NO se pasa por argumento: quedaría en el historial del shell y en \`ps\`." >&2
+        echo "   \`register\` lo pide por stdin. Córrelo en un terminal humano." >&2
+        return $OPS_RC_USAGE ;;
+      *) shift ;;
+    esac
+  done
+  command -v python3 >/dev/null 2>&1 || {
+    echo "⛔ register necesita python3 para escribir las credenciales." >&2; return $OPS_RC_OFFLINE; }
+
+  wt="$(config_candidate_root)"
+  main="$(config_main_clone_root)"
+  localfile="$wt/.claude/state/runtime.credentials"
+  mainfile=""
+  if [ -n "$main" ] && [ "$main" != "$wt" ]; then mainfile="$main/.claude/state/runtime.credentials"; fi
+
+  if [ -f "$localfile" ] && [ "$force" != 1 ]; then
+    echo "este árbol YA tiene identidad propia — no se toca nada:"
+    echo "  raíz:      $wt"
+    echo "  agente:    $(runtime_credentials_field_at "$localfile" agent_key)"
+    echo "  proyecto:  $(runtime_credentials_field_at "$localfile" project_id)"
+    echo "(para re-registrarlo con OTRO token: \`register --force\`)"
+    return $OPS_RC_OK
+  fi
+
+  # La URL no es secreta y es la MISMA del proyecto: se hereda del principal si no se da.
+  if [ -z "$url" ]; then
+    url="$(runtime_credentials_field_at "$localfile" runtime_url)"
+    [ -n "$url" ] || url="$(runtime_credentials_field_at "$mainfile" runtime_url)"
+  fi
+  case "$url" in
+    http://*|https://*) : ;;
+    *)
+      echo "⛔ no hay runtime_url que usar (ni --runtime-url, ni credenciales del clon principal)." >&2
+      echo "   Pásala explícita: \`register --runtime-url https://…\`" >&2
+      return $OPS_RC_USAGE ;;
+  esac
+
+  mainkey="$(runtime_credentials_field_at "$mainfile" agent_key)"
+
+  if [ -t 0 ]; then
+    printf 'Token de agente para este árbol (no se muestra en pantalla): ' >&2
+    IFS= read -rs token
+    printf '\n' >&2
+  else
+    IFS= read -r token || token=""
+  fi
+  token="$(printf '%s' "$token" | tr -d '[:space:]')"
+  [ -n "$token" ] || { echo "⛔ token vacío: no se registró nada." >&2; return $OPS_RC_USAGE; }
+
+  # Compuerta barata y decisiva, ANTES de la red: si el token es el del clon principal, el hub
+  # devolverá su misma identidad — el `agent_key` va grabado en el token, no se crea al
+  # registrar. Preguntarlo por HTTP solo añadiría una llamada al mismo veredicto.
+  if [ -n "$mainfile" ] && [ "$token" = "$(runtime_credentials_field_at "$mainfile" project_token)" ]; then
+    token=""
+    echo "⛔ ese token es la identidad del clon principal: registrarlo aquí daría el MISMO" >&2
+    echo "   agent_key y el claim te devolvería el trabajo que ya tiene reclamado el otro árbol." >&2
+    echo "   Pide al ADMIN un token con \`agent_id\` distinto (uno por agente)." >&2
+    echo "   El fichero del clon principal NO se ha tocado." >&2
+    return $OPS_RC_REJECTED
+  fi
+
+  if [ -f "$localfile" ]; then
+    backup="$(mktemp)" && cp "$localfile" "$backup" 2>/dev/null || backup=""
+  fi
+
+  if ! TRYCORE_REGISTER_TOKEN="$token" runtime_credentials_seed_at "$localfile" "$url"; then
+    token=""
+    _reg_rollback "$localfile" "$backup"
+    echo "⛔ no se pudo escribir $localfile — revisa permisos." >&2
+    return $OPS_RC_OFFLINE
+  fi
+  token=""   # el secreto ya está en el fichero 0600: fuera de las variables del shell
+
+  hv="$(harness_version)"
+  at="$(harness_asset_types)"
+  runtime_register "$hv" "$at"
+  rc=$?
+  if [ "$rc" -ne 0 ]; then
+    _reg_rollback "$localfile" "$backup"
+    if [ "$rc" -eq 2 ]; then
+      echo "⛔ el hub rechaza esta versión del arnés ($hv): incompatible_version." >&2
+      echo "   Actualiza el paquete y repite \`register\`." >&2
+      return $OPS_RC_REJECTED
+    fi
+    case "$(runtime_http_status)" in
+      401|403)
+        echo "⛔ el hub no acepta ese token (HTTP $(runtime_http_status)): pide al ADMIN uno válido" >&2
+        echo "   para este proyecto. Nada quedó escrito." >&2
+        return $OPS_RC_REJECTED ;;
+      *)
+        echo "OFFLINE: no se pudo registrar contra $url (HTTP $(runtime_http_status))." >&2
+        echo "  Nada quedó escrito: repite \`register\` cuando haya red." >&2
+        return $OPS_RC_OFFLINE ;;
+    esac
+  fi
+
+  newkey="$(runtime_credentials_field_at "$localfile" agent_key)"
+  if [ -z "$newkey" ]; then
+    _reg_rollback "$localfile" "$backup"
+    echo "⛔ el hub respondió 200 pero sin \`agent_key\`: sin identidad verificable no se da" >&2
+    echo "   de alta el árbol. Nada quedó escrito." >&2
+    return $OPS_RC_REJECTED
+  fi
+  if [ -n "$mainkey" ] && [ "$newkey" = "$mainkey" ]; then
+    _reg_rollback "$localfile" "$backup"
+    echo "⛔ ese token resuelve al MISMO agent_key que el clon principal ($mainkey): no es una" >&2
+    echo "   identidad nueva. El \`agent_key\` lo graba el ADMIN en el token al emitirlo —" >&2
+    echo "   pide uno con \`agent_id\` distinto. El fichero del clon principal NO se ha tocado." >&2
+    return $OPS_RC_REJECTED
+  fi
+  rm -f "$backup"
+
+  # A partir de aquí `config_root()` ancla en este árbol, y con él TODA la resolución de
+  # config: si `build-config.json` no viajó al worktree (no está versionado en el consumidor),
+  # `runtime.mode` caería al default `legacy` y el árbol recién dado de alta dejaría de hablar
+  # con el hub — el registro habría «funcionado» apagando justo lo que venía a encender. Se
+  # copia del principal solo si aquí no hay ninguno: nunca se pisa una config local.
+  if [ -n "$main" ] && [ ! -f "$wt/.claude/config/build-config.json" ] \
+     && [ -f "$main/.claude/config/build-config.json" ]; then
+    mkdir -p "$wt/.claude/config"
+    cp "$main/.claude/config/build-config.json" "$wt/.claude/config/build-config.json" 2>/dev/null \
+      && echo "  (build-config.json copiado del clon principal: modo $(ops_mode))"
+  fi
+
+  echo "árbol dado de alta con identidad propia:"
+  echo "  raíz:      $wt"
+  echo "  agente:    $newkey"
+  echo "  proyecto:  $(runtime_credentials_field_at "$localfile" project_id)"
+  [ -n "$mainkey" ] && echo "  (distinto del clon principal: $mainkey — su fichero no se tocó)"
+  echo "Desde aquí el claim, los gates y el heartbeat son de ESTE árbol. Siguiente paso:"
+  echo "  bash .claude/hooks/build/slice-ops.sh claim"
+  return $OPS_RC_OK
+}
+
 SUB="${1:-}"
 [ $# -gt 0 ] && shift
+
+# [#74] Compuerta de identidad ANTES de despachar. Las operaciones de ESCRITURA — todo lo que
+# firma un acto con el `agent_key` o toca la cola/los ledgers — abortan si este árbol heredó la
+# identidad del clon principal. Las LECTURAS (`mode`, `next-step`, `status`, los `*-status`)
+# quedan fuera a propósito: son el diagnóstico de un worktree que aún no se dio de alta, y
+# `status` avisa de quién es el estado que enseña. `register` tampoco entra: es la salida.
+case " claim phase gate submit archive wiring progress checkpoint fact propose-asset propose-epic epic-writeback graph-sync escalate " in
+  *" $SUB "*) ops_guard_own_identity "$SUB" || exit $? ;;
+esac
+
 case "$SUB" in
   mode) ops_mode; exit 0 ;;
+  register) cmd_register "$@"; exit $? ;;
   claim) cmd_claim "$@"; exit $? ;;
   next-step) cmd_next_step; exit $? ;;
   phase) cmd_phase "$@"; exit $? ;;
@@ -1631,6 +2203,8 @@ case "$SUB" in
   propose-epic) cmd_propose_epic "$@"; exit $? ;;
   epic-status) cmd_epic_status "$@"; exit $? ;;
   epic-writeback) cmd_epic_writeback "$@"; exit $? ;;
+  graph-sync) cmd_graph_sync "$@"; exit $? ;;
+  graph-sync-status) cmd_graph_sync_status "$@"; exit $? ;;
   status) cmd_status "$@"; exit $? ;;
   escalate) cmd_escalate "$@"; exit $? ;;
   ""|-h|--help|help) usage; exit $OPS_RC_USAGE ;;