@trycore/spec-build-harness 0.14.2 → 0.16.0

package/docs/runtime/protocolo-cliente-runtime.md

@@ -9,6 +9,11 @@
 - **Token de proyecto:** emitido por un ADMIN en el hub, entregado al desarrollador, configurado una vez con `trycore-build init --runtime-url --runtime-token` (se guarda en `.claude/state/runtime.credentials`, `0600`, sembrado en `.gitignore` por `init`). Todas las llamadas: `Authorization: Bearer <token>`.
 - **Registro:** `POST /agents/register {harness_version, asset_types}` → el servidor responde `{agent_key, project_id, harness_version, poll_interval_s, lease_ttl_s, manifest_hash, catalog{…}}`; el cliente (`runtime_register`) persiste hoy solo `agent_key`, `project_id`, `poll_interval_s`, `lease_ttl_s` y `manifest_hash` — `catalog` (tipos de asset) todavía no se persiste (el cliente ya envía `asset_types` desde `.claude/asset-types.json`, pero no consume el `catalog` de vuelta), `harness_version` no se re-persiste (ya se conoce localmente). Los intervalos los dicta el servidor (el cliente no los hardcodea). `409 incompatible_version` ⇒ mensaje claro con la versión mínima requerida (cuerpo `{error, min_version}`).
 - **Identidad local:** `agent_key`/`project_id` persisten en `.claude/state/runtime.credentials` (`0600`, protegido en `.gitignore` desde el primer `init`); un mismo clon re-registrado reactiva su agente (no crea otro): `runtime_register` hace upsert sobre el fichero existente, nunca lo recrea desde cero.
+- **Un token = un agente.** `POST /agents/register` **no crea identidad**: el `agent_key` es el `agent_id` que el ADMIN grabó en el token al emitirlo. Dos árboles con el mismo token son **el mismo agente** para el hub, y el segundo `claim` devuelve el slice que ya tiene reclamado el primero. Para dos agentes hacen falta **dos tokens**.
+- **Identidad por árbol de trabajo (`git worktree`, issue #74).** El estado del arnés está en `.gitignore` y **no viaja** a un `git worktree add`. `config_root()` cae entonces al clon principal (`--git-common-dir`) para que el árbol nuevo no quede huérfano de contexto — pero ese fallback vale para **leer**, no para **escribir**: sin credenciales propias, el worktree firmaría cada acto con el `agent_key` del clon principal, reportaría los hashes del árbol equivocado y compartiría su heartbeat. Por eso:
+  - Toda operación de **escritura** (`slice-ops.sh claim|phase|gate|submit|archive|wiring|progress|checkpoint|fact|propose-asset|propose-epic|epic-writeback|graph-sync|escalate` y `release-ops.sh front-integration`) aborta con **rc 9** antes de tocar la red si la identidad es heredada.
+  - Las **lecturas** (`mode`, `next-step`, `status`, `epic-status`, `graph-sync-status`) conservan el fallback: son el diagnóstico del árbol que aún no se dio de alta. `status` lo encabeza con `identidad: ⚠ HEREDADA del clon principal … — solo lectura`.
+  - El alta es explícita: **`slice-ops.sh register`** (§10). Con ella, `ops_context_hashes`, el heartbeat, la outbox y los ledgers pasan a ser por-worktree solos — todos cuelgan de `config_root()`.
 
 ## 2. Mapeo hook → endpoint (la telemetría es del harness, no del modelo)
 
@@ -177,11 +182,11 @@ agente jamás publica contexto.**
 | Situación | Comportamiento del cliente |
 |---|---|
 | `401/403` (token inválido/revocado) | Detener claims; mensaje accionable ("pide un token nuevo al ADMIN"); guards siguen operando con el último lock. |
-| `409` en claim | Un reintento inmediato; luego informar "otro agente tomó la tarea" y pedir la siguiente. |
+| `409` en claim | Un reintento inmediato; luego informar "otro agente tomó la tarea" y pedir la siguiente. Los motivos llegan **bajo `detail`**, no en la raíz: el **drift de contexto** se reconoce por FORMA (`detail` dict con `manifest_hash`, que es el hash al que sincronizar) y el resto por el texto que el hub construye en un solo sitio (contención → reintentable; «no hay trabajo sin contexto declarado» → `rc 6` sin reintento). Lo que el cliente enseña es la prosa del hub, nunca el JSON crudo. |
 | `422` (evento/veredicto rechazado por transición ilegal o schema) | **No reintentar**: mostrar la razón del servidor al modelo/usuario (compuerta mecánica funcionando); registrar localmente. |
 | Timeout/red caída | Modo offline (§4/§5); jamás bloquear PreToolUse ni el trabajo local. |
 | `409` en el renew de lease (`PUT /leases/renew`) | **No existe 410**: el servidor responde siempre `409` de cuerpo único (anti-oráculo). El daemon marca `lease_lost` en `.claude/state/heartbeat-status.json`, **no se apaga** (sigue despachando la cola) y la statusline muestra `⚠ lease`. La skill detiene el trabajo, hace checkpoint local y vuelve a reclamar. |
-| `409` `stale_graph` en `tasks/next` o en la propuesta | Grafo local rancio: anotar desfase, refrescar y reintentar **una vez**; segundo rechazo → `rc 6` con el desfase nombrado. En la cola: conservar y re-estampar con la versión del momento; se aparta al **tercer rechazo contra la MISMA versión local estampada** (si la versión cambió entre medias, hubo refresco de verdad y la racha vuelve a cero). El contador va con su versión (`graph_409`, `graph_409_at_version`) dentro del fichero de la outbox: contar rechazos a secas agotaría las tres vidas de la propuesta sin que hubiera ocurrido ni un refresco, porque el despacho corre en cada `Stop` mientras el refresco de contexto va a `runtime.context_refresh_s` (45 s, y `0` lo **desactiva**). |
+| `409` de **grafo rancio** en `tasks/next` o en el carril directo | El hub lo emite como `{"detail": {"error": "graph_version_stale", "graph_version": <vigente>}}` — anidado bajo `detail`, que es donde FastAPI pone el cuerpo de un `HTTPException`. El cliente lo lee con `runtime_stale_graph_version`, que acepta esa forma y la plana `{"reason": "stale_graph"}` de una instancia anterior al contrato. Conducta: anotar desfase, refrescar y reintentar **una vez**; segundo rechazo → `rc 6` con el desfase nombrado. En la cola: conservar y re-estampar con la versión del momento; se aparta al **tercer rechazo contra la MISMA versión local estampada** (si la versión cambió entre medias, hubo refresco de verdad y la racha vuelve a cero). El contador va con su versión (`graph_409`, `graph_409_at_version`) dentro del fichero de la outbox: contar rechazos a secas agotaría las tres vidas de la propuesta sin que hubiera ocurrido ni un refresco, porque el despacho corre en cada `Stop` mientras el refresco de contexto va a `runtime.context_refresh_s` (45 s, y `0` lo **desactiva**). |
 | Reloj local desviado | El cliente usa siempre `expires_at` del servidor, nunca calcula TTL con reloj propio. |
 
 ## 8. Seguridad del cliente
@@ -215,6 +220,7 @@ modo, valida en local lo que es barato validar y encola lo que no pudo entregar.
 | Comando | Superficie |
 |---|---|
 | `slice-ops.sh mode` | ninguna (lee `build-config.json`) |
+| `slice-ops.sh register [--runtime-url U] [--force]` | `POST /agents/register` con un token **propio de este árbol**. Da de alta un worktree como agente distinto (§1). El token entra por **stdin** (prompt si hay TTY), nunca por argumento —`--token` sale con rc 2— porque en argv queda en el historial del shell y en `ps`; por lo mismo es un comando de terminal humano y **no** se invoca desde dentro de un claim (los hooks no tienen TTY y un `read` colgaría la llamada). Orden obligado: siembra el fichero local **primero** (si no, el upsert caería sobre las credenciales del clon principal y le pisaría la identidad), registra, y **verifica que el `agent_key` obtenido difiera** del del principal. Cualquier fallo revierte: el árbol queda con identidad propia y verificada, o exactamente como estaba; el fichero del clon principal no se toca nunca. `0` alta (o ya registrado) · `2` uso · `5` sin red · `6` mismo agente que el principal / token rechazado |
 | `slice-ops.sh claim` | `POST /tasks/next` (§3); `--epic` falla explícito, rc 2 (no hay claim dirigido, §3.6) |
 | `slice-ops.sh next-step` | ninguna: lo **deriva el cliente** desde la caché de proyección |
 | `slice-ops.sh phase <to>` | evento(s) `phase_advanced {to}` en cadena (issue #52): el hub lleva la fase con orden ESTRICTO (`dor→change→red→green→refactor→smoke→api→data→dod→pr`, `domain.py` `PHASES`) y solo acepta la fase siguiente exacta. El cliente emite la cadena que falte desde la fase conocida (proyección ∪ `phase_advanced` pendientes en la cola) hasta `<to>`; idempotente (nada si ya está). `archived` no se reporta aquí (lo produce `archive`). Siempre por cola en `runtime` (tipo protegido de la cota: evictar un eslabón haría ilegal todo lo posterior); espejo en `dual` (`phase_advanced` ∈ `TIPOS_DE_ESPEJO`) |
@@ -235,6 +241,10 @@ modo, valida en local lo que es barato validar y encola lo que no pudo entregar.
 | `release-ops.sh close-hint <line>` | **ninguna**: el cierre es humano, con PDP |
 | `release-ops.sh front-integration <front>` | `POST /fronts/{id}/members/{agent_key}/integration`; **sin fallback offline** (rc 5: `front_integration_reported` no existe en el catálogo v2, issue #44) |
 
+**Códigos de salida.** `0` ok · `2` uso · `3` legacy · `4` sin slice · `5` offline · `6` rechazado ·
+`7` sin trabajo · `8` fuera del catálogo de espejo · **`9` identidad heredada** (#74: este árbol
+opera con las credenciales del clon principal; da de alta el worktree con `register`).
+
 **Forma del borrador de `propose-epic --file`:**
 
 ```json
@@ -271,13 +281,62 @@ El hub descarta los campos que no reconoce (`extra="ignore"`): mandar `acceptanc
 `7` sin trabajo.
 
 **Modo `dual`:** el fichero es primario y estos comandos **espejan** cada transición a
-`POST /projects/{project_id}/mirror/transitions` con la identidad fichero-primaria
-(`slice_ref: {epic_code, openspec_change, branch, phase}`) y `origin: "mirror"`. Un rechazo del
-reducer **no bloquea** el trabajo local: se avisa y queda como discrepancia del comparador.
+`POST /projects/{project_id}/mirror/transitions`. El cuerpo es `MirrorTransitionsIn`:
+
+```json
+{"transitions": [{"client_event_id": "<uuid>", "epic_code": "EP-009",
+                  "event_type": "gate_verdict", "payload": {…}}]}
+```
+
+La identidad fichero-primaria viaja como `epic_code` **en el sobre**, que es donde el hub la lee;
+dentro del `payload` no cabe nada que el schema del tipo no declare (`extra="forbid"`). Ni
+`origin` ni `occurred_at` viajan: la marca de origen-espejo la estampa el servidor —lo que dijera
+el cliente no elegiría el origen— y los relojes de cliente entran **solo** por el import. El
+reporte es **por elemento** (`results[].status` ∈ `applied|duplicate|rejected` con su `reason`), y
+un rechazo **no bloquea** el trabajo local: se avisa con el motivo del hub y queda como
+discrepancia del comparador.
+
+**Enumeración normativa del espejo** (`TIPOS_DE_ESPEJO`, replicada en `OPS_MIRROR_TYPES` con test
+anti-drift): `slice_opened`, `phase_advanced`, `phase_reverted`, `gate_verdict`,
+`wiring_item_updated`, `wiring_checklist_seeded`, `checkpoint_recorded`, `progress_noted`,
+`handoff_recorded`. Un tipo fuera de ella **no gasta red**: se corta en local con `rc 8`. Ahí caen
+`slice_escalated`, `slice_archived`, `slice_submitted` (existen en el catálogo del hub pero no son
+espejables) y `release_verdict_reported` / `front_integration_reported` (no existen en el catálogo:
+sus canales de espejo son trabajo **hub-side**).
+
+### Re-sync del grafo (`graph-sync` / `graph-sync-status`, EP-OR-17)
+
+El grafo del hub se siembra con el import de ADMIN y, hasta EP-OR-17, no volvía a moverse: las
+épicas que discovery añadía después no tenían por dónde entrar, y toda transición de un slice cuya
+épica falta en el grafo rebota con «la épica no existe en el grafo del proyecto». El carril nuevo
+lo cierra sin dar al agente la potestad de mutar el grafo — **propone**, el hub calcula el delta y
+un humano aprueba.
+
+| Verbo y ruta | Cuerpo | Respuestas |
+|---|---|---|
+| `POST /projects/{id}/agent/graph-sync-proposals` | `{"bundle": {"epics": […]}, "graph_version": <vigente\|null>, "client_event_id": "<≤64>"}` | `201` propuesta `PROPOSED` · `200 {"empty_delta": true}` el grafo ya está al día · `409` `detail` dict = grafo rancio, `detail` string = el `client_event_id` ya identifica otro agregado · `422` bundle inválido (rechazo total, sin fila ni evento) · `404` anti-oráculo |
+| `GET /projects/{id}/agent/graph-sync-proposals/{proposal_id}` | — | `200` con `status`, `delta`, `graph_version_applied` o `reject_reason` · `404` anti-oráculo |
+
+- El **bundle** lo construye `scripts/lib/graph-bundle.py --for-sync` desde los docs de discovery.
+  `GraphSyncBundle` es `extra="forbid"` y admite **solo** `epics`: las claves del bundle de
+  preparación (`bundle_version`, `kind`, `project_ref`, `warnings`…) serían un `422`. Lo que en el
+  bundle de import es un aviso aquí es un **rechazo local** (`rc 2`): no hay humano revisando en
+  medio, y el hub rechaza el grafo entero ante una sola épica mal formada.
+- El **`client_event_id` es determinista** (`<agent_key>:graph-sync:<n>`, con `n` = entradas del
+  ledger + 1; sha256 truncado del `agent_key` si no cabe en 64). El reintento lo reusa y el hub
+  deduplica, en vez de dejar dos propuestas del mismo grafo esperando aprobación.
+- El **reintento del 409** lo hace el comando, no el despachador: refresca `/agent/context` y
+  vuelve a despachar **una vez**, con lo que el estampado toma la versión nueva. El bundle no
+  depende de la versión del grafo, solo el sello que lo acompaña.
+- Tras la aprobación **no hay nada más que hacer**: las historias nuevas entran solas al reparto
+  del claim. La lógica de claim del cliente no cambia.
+- El **ledger local** vive en `.claude/state/graph-sync-proposals.json` (protegido en
+  `.gitignore`), separado del de propuestas de épica: un re-sync no es una propuesta de épica.
 
 **Lo que el agente NO hace** (superficies humanas, con PDP): cerrar una release, planificar/abrir/
-drenar/cerrar un front, subir el bundle de import del grafo y publicar contexto. El arnés prepara,
-propone y reporta; la persona decide en la consola del hub.
+drenar/cerrar un front, **aprobar o rechazar un re-sync del grafo**, subir el bundle de import del
+grafo y publicar contexto. El arnés prepara, propone y reporta; la persona decide en la consola del
+hub.
 
 ---
 

package/hooks/build/lib/config.sh

@@ -16,23 +16,71 @@
 # Por eso, cuando el árbol actual no tiene estado, se cae al clon principal
 # (--git-common-dir), que es donde vive de verdad. Idempotente para un clon
 # normal: si el candidato ya tiene estado, se devuelve tal cual.
+#
+# [#74] Ese fallback vale para LEER, nunca para ESCRIBIR: quien vaya a transicionar algo
+# tiene que preguntar antes por `config_is_inherited_root` (más abajo) y abortar, o estará
+# operando con la identidad del clon principal sin saberlo.
 config_root() {
   local candidate
   candidate="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
   [ -f "$candidate/.claude/state/runtime.credentials" ] && { echo "$candidate"; return; }
 
-  local common main
-  common="$(git -C "$candidate" rev-parse --git-common-dir 2>/dev/null)" || common=""
-  if [ -n "$common" ]; then
-    case "$common" in /*) ;; *) common="$candidate/$common" ;; esac
-    main="$(cd "$common/.." 2>/dev/null && pwd)" || main=""
-    if [ -n "$main" ] && [ -f "$main/.claude/state/runtime.credentials" ]; then
-      echo "$main"; return
-    fi
+  local main
+  main="$(config_main_clone_root)"
+  if [ -n "$main" ] && [ -f "$main/.claude/state/runtime.credentials" ]; then
+    echo "$main"; return
   fi
   echo "$candidate"
 }
 
+# ── Identidad por árbol de trabajo [#74] ─────────────────────────────────────────────
+# El fallback de config_root es deliberado para LEER (un worktree sin estado propio sigue
+# viendo el contexto del proyecto), pero es veneno para ESCRIBIR: un worktree sin
+# credenciales propias impersona en silencio al agente del clon principal — reclama con su
+# `agent_key`, reporta los hashes de SU árbol (no del propio), comparte su heartbeat y, al
+# registrarse, le pisaría el fichero de credenciales. Estos tres helpers son la señal que
+# permite a las operaciones de escritura fallar rápido en vez de suplantar.
+
+# _config_phys <ruta> — forma FÍSICA de una ruta (resuelve symlinks). En macOS /var es un
+# symlink a /private/var: comparar rutas sin normalizar mide cómo se escribió el path, no a
+# qué apunta. Ante una ruta inaccesible devuelve la entrada tal cual — nunca lanza.
+_config_phys() {
+  (cd "$1" 2>/dev/null && pwd -P) || printf '%s\n' "$1"
+}
+
+# config_candidate_root — la raíz que corresponde a ESTE árbol de trabajo, SIN fallback:
+# `CLAUDE_PROJECT_DIR` o el toplevel del árbol actual. Es el otro extremo de la comparación
+# de identidad (config_root es «de quién es el estado que voy a usar»; esto es «dónde estoy»).
+config_candidate_root() {
+  local candidate
+  candidate="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+  _config_phys "$candidate"
+}
+
+# config_main_clone_root — raíz del clon principal según `--git-common-dir` ("" si no hay
+# git). En un clon normal coincide con el propio árbol; en un worktree apunta al clon que lo
+# creó. Es la única forma de leer la identidad del principal sin depender de config_root
+# (que es justo lo que puede estar heredado).
+config_main_clone_root() {
+  local candidate common main
+  candidate="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+  common="$(git -C "$candidate" rev-parse --git-common-dir 2>/dev/null)" || common=""
+  [ -n "$common" ] || { echo ""; return; }
+  case "$common" in /*) ;; *) common="$candidate/$common" ;; esac
+  main="$(cd "$common/.." 2>/dev/null && pwd -P)" || main=""
+  echo "$main"
+}
+
+# config_is_inherited_root — rc 0 si el estado que se va a usar NO es el de este árbol, es
+# decir: config_root cayó al clon principal. rc 1 en un clon normal, en un worktree ya
+# registrado y en un proyecto sin arnés (donde no hay identidad que heredar).
+config_is_inherited_root() {
+  local here there
+  here="$(config_candidate_root)"
+  there="$(_config_phys "$(config_root)")"
+  [ -n "$here" ] && [ -n "$there" ] && [ "$here" != "$there" ]
+}
+
 # config_get <clave.punteada> <default>
 config_get() {
   local key="$1" def="$2" file

package/hooks/build/lib/harness-meta.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# harness-meta.sh — metadatos del PAQUETE instalado (versión del arnés y catálogo de asset
+# types). Extraído de session-start.sh [#74] para que `slice-ops.sh register` mande
+# exactamente el mismo `harness_version` que el registro de arranque de sesión: dos lecturas
+# distintas de la misma versión acabarían con un worktree rechazado por
+# `incompatible_version` y el clon principal aceptado, o al revés.
+# Fail-open, igual que config.sh: nunca lanza; sin fichero devuelve un valor neutro.
+
+source "$(dirname "${BASH_SOURCE[0]}")/config.sh"
+
+# harness_pkg_root — raíz del PAQUETE (no del proyecto). Los hooks se instalan como symlinks
+# por fichero (linkChildren), así que hay que resolver la cadena de enlaces a mano:
+# `readlink -f` no es portable al BSD readlink de macOS. Este fichero vive en
+# `<pkg>/hooks/build/lib/`, de ahí los tres niveles.
+harness_pkg_root() {
+  local src="${BASH_SOURCE[0]}" target i=0
+  while [ -L "$src" ] && [ "$i" -lt 10 ]; do
+    target="$(readlink "$src" 2>/dev/null)" || break
+    case "$target" in
+      /*) src="$target" ;;
+      *)  src="$(dirname "$src")/$target" ;;
+    esac
+    i=$((i + 1))
+  done
+  (cd "$(dirname "$src")/../../.." >/dev/null 2>&1 && pwd -P) 2>/dev/null
+}
+
+# harness_version — versión instalada en el consumidor; si no, la del paquete.
+# [#74] El marcador `.claude/.build-harness-version` está en .gitignore en modo symlink: NO
+# viaja a un `git worktree add`. Por eso se mira también el clon principal antes de caer al
+# paquete — un worktree recién dado de alta no tiene por qué mentir sobre su versión.
+harness_version() {
+  local f pkg root
+  for root in "$(config_root)" "$(config_candidate_root)" "$(config_main_clone_root)"; do
+    [ -n "$root" ] || continue
+    f="$root/.claude/.build-harness-version"
+    [ -f "$f" ] && { tr -d ' \n' < "$f"; return; }
+  done
+  pkg="$(harness_pkg_root)"
+  if [ -n "$pkg" ] && [ -f "$pkg/VERSION" ]; then
+    tr -d ' \n' < "$pkg/VERSION"
+    return
+  fi
+  echo "0.0.0"
+}
+
+# harness_asset_types — el array `types` de asset-types.json del paquete (protocolo §6).
+# Cadena de resolución: plugin > copia en .claude/ (la siembra es del sub-slice D) >
+# paquete resuelto por symlink. Sin fichero: "[]" — el registro sigue funcionando.
+harness_asset_types() {
+  local pkg candidates f
+  pkg="$(harness_pkg_root)"
+  candidates="${CLAUDE_PLUGIN_ROOT:-}/asset-types.json
+$(config_root)/.claude/asset-types.json
+${pkg:-}/asset-types.json"
+  while IFS= read -r f; do
+    case "$f" in /asset-types.json|asset-types.json) continue ;; esac
+    [ -f "$f" ] || continue
+    python3 - "$f" <<'PY' 2>/dev/null && return
+import json,sys
+try:
+    d=json.load(open(sys.argv[1]))
+    t=d.get("types")
+    print(json.dumps(t if isinstance(t,list) else [],ensure_ascii=False))
+except Exception:
+    raise SystemExit(1)
+PY
+  done <<EOS
+$candidates
+EOS
+  echo "[]"
+}

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

@@ -46,11 +46,39 @@ except Exception:
 PY
 }
 
+# runtime_credentials_field_at <fichero> <clave> — lee un campo de un fichero de credenciales
+# CONCRETO, sin pasar por config_root(). [#74] Es la única forma de mirar la identidad del clon
+# principal desde un worktree: `runtime_field` resuelve por config_root(), que es justo lo que
+# puede estar heredado — preguntarle «¿cuál es el agent_key del principal?» devolvía el propio.
+runtime_credentials_field_at() {
+  local file="$1" key="$2"
+  [ -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)"
+  runtime_credentials_merge_at "$(runtime_credentials_path)" "$1"
+}
+
+# runtime_credentials_merge_at <fichero> <json> — el mismo upsert sobre una RUTA EXPLÍCITA.
+# [#74] `register` tiene que sembrar el fichero del worktree ANTES de que exista, y por tanto
+# antes de que config_root() pueda anclar en local: pasando por runtime_credentials_path()
+# habría hecho merge del token nuevo sobre el fichero del clon principal, pisándole la
+# identidad al agente que está construyendo ahí.
+runtime_credentials_merge_at() {
+  local file="$1" fragment="$2" dir
   dir="$(dirname "$file")"
   mkdir -p "$dir"
   command -v python3 >/dev/null 2>&1 || return 1
@@ -78,6 +106,41 @@ except Exception:
 PY
 }
 
+# runtime_credentials_seed_at <fichero> <runtime_url> — siembra credenciales en una RUTA
+# EXPLÍCITA con el token tomado de `TRYCORE_REGISTER_TOKEN`. [#74] El token viaja por ENTORNO
+# y no por argv a propósito: `runtime_credentials_merge_at` recibe el fragmento como argumento
+# y en una máquina compartida un `ps` lo vería. Es el único camino por el que un secreto entra
+# de nuevo al fichero, así que es el único que necesita esta precaución.
+# Escribe un documento NUEVO, no un upsert: dar de alta un árbol es estrenar identidad, y
+# conservar el `agent_key` anterior haría que una respuesta 200 sin `agent_key` pareciera un alta
+# buena (`register --force` para rotar el token es justo el caso). Lo que el hub devuelva vuelve a
+# entrar por `runtime_register`. Escritura atómica + chmod 0600.
+runtime_credentials_seed_at() {
+  local file="$1" url="$2" dir
+  dir="$(dirname "$file")"
+  mkdir -p "$dir"
+  command -v python3 >/dev/null 2>&1 || return 1
+  python3 - "$file" "$url" <<'PY' 2>/dev/null || return 1
+import json,os,sys,tempfile
+path,url=sys.argv[1],sys.argv[2]
+tok=os.environ.get("TRYCORE_REGISTER_TOKEN","")
+if not tok:
+    raise SystemExit(1)
+d={"runtime_url":url,"project_token":tok}
+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
 }
@@ -349,6 +412,41 @@ PY
 # runtime_graph_clear_stale — el desfase dejó de existir (la proyección alcanzó al servidor).
 runtime_graph_clear_stale() { rm -f "$(runtime_graph_status_path)" 2>/dev/null; return 0; }
 
+# runtime_stale_graph_version <respuesta-json> — ¿este 409 dice que nuestro grafo va rancio?
+# rc 0 = sí (imprime la versión vigente del servidor, o vacío si no la manda) · rc 1 = no.
+#
+# [EP-OR-17] Existe porque el cliente leía `{"reason":"stale_graph"}` en la RAÍZ y el hub emite
+# `{"detail":{"error":"graph_version_stale","graph_version":N}}` — un HTTPException de FastAPI
+# anida SIEMPRE bajo `detail`, y el literal `stale_graph` no aparece en ninguna parte de su
+# backend. Con la lectura vieja, un claim con grafo rancio NO se reintentaba y una propuesta se
+# apartaba como rechazo definitivo: dos caminos que existían para tolerar el desfase y que en
+# realidad nunca se tomaban. Se aceptan las dos formas — si una instancia anterior al contrato
+# emitiera la plana, seguiría entendiéndose.
+# Fail-CLOSED a propósito, al revés que el resto del cliente: ante JSON ilegible o sin python3
+# devuelve rc 1 («no es un stale»). Tratar un rechazo cualquiera como grafo rancio lo dejaría
+# reintentando en bucle contra un hub que nunca va a aceptarlo.
+runtime_stale_graph_version() {
+  command -v python3 >/dev/null 2>&1 || return 1
+  printf '%s' "$1" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+except Exception:
+    raise SystemExit(1)
+if not isinstance(d,dict):
+    raise SystemExit(1)
+det=d.get("detail")
+fuente=det if isinstance(det,dict) else d
+marca=fuente.get("error") or fuente.get("reason") or ""
+if marca not in ("graph_version_stale","stale_graph"):
+    raise SystemExit(1)
+v=fuente.get("graph_version")
+if v is None:
+    v=d.get("graph_version")
+sys.stdout.write("" if v is None else str(v))
+' 2>/dev/null
+}
+
 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:
@@ -408,7 +506,8 @@ PY
   runtime_outbox_enforce_cap >/dev/null
 }
 
-# runtime_enqueue_direct <type> <method> <path> <payload_file> [stamp_graph_version] — encola
+# runtime_enqueue_direct <type> <method> <path> <payload_file> [stamp_graph_version]
+#                        [client_event_id] — encola
 # una petición del CARRIL DIRECTO [#62]: un hecho que NO viaja en el lote de `POST /events`
 # sino a su propio endpoint (hoy: la propuesta de épica, hub#113). Comparte con la cola de
 # eventos el directorio, el formato en disco, la cota y el sentinela de flush; lo único
@@ -419,18 +518,25 @@ PY
 # [#63] Con `1` en el 5º argumento, el fichero se marca para que el DESPACHO le estampe la
 # versión de grafo vigente. Sellarla al encolar sería un error: una propuesta que espera dos
 # días en la cola offline saldría con la versión de hace dos días y nacería condenada al 409.
+# [EP-OR-17] El 6º argumento fija el `client_event_id` en vez de generarlo: lo usa el re-sync
+# del grafo, donde el reintento tiene que llevar la MISMA identidad para que el hub deduplique
+# en vez de crear una segunda propuesta. Vacío (o ausente) = uuid4, como siempre.
 runtime_enqueue_direct() {
-  local type="$1" method="$2" path="$3" pfile="$4" stamp="${5:-0}" dir
+  local type="$1" method="$2" path="$3" pfile="$4" stamp="${5:-0}" cid_fijo="${6:-}" dir
   dir="$(runtime_outbox_dir)"; mkdir -p "$dir"
   command -v python3 >/dev/null 2>&1 || return 1
-  python3 - "$dir" "$type" "$method" "$path" "$pfile" "$stamp" <<'PY' 2>/dev/null || return 1
+  python3 - "$dir" "$type" "$method" "$path" "$pfile" "$stamp" "$cid_fijo" <<'PY' 2>/dev/null || return 1
 import json,sys,os,tempfile,uuid,datetime
-dir_,typ,method,path,pfile,stamp=sys.argv[1],sys.argv[2],sys.argv[3],sys.argv[4],sys.argv[5],sys.argv[6]
+dir_,typ,method,path,pfile,stamp,cid_fijo=sys.argv[1],sys.argv[2],sys.argv[3],sys.argv[4],sys.argv[5],sys.argv[6],sys.argv[7]
 try:
     payload=json.load(open(pfile))
 except Exception:
     payload={}
-cid=str(uuid.uuid4())
+# [EP-OR-17] Un cid FIJADO por el productor es lo que hace idempotente el reintento: el hub
+# deduplica por `client_event_id`, así que re-encolar el mismo re-sync tras un 409 de grafo
+# rancio no crea una segunda propuesta del mismo grafo. Sin él se conserva el uuid4 de siempre,
+# que es lo que quiere el carril de propuesta de épica (cada propuesta es una épica distinta).
+cid=cid_fijo or str(uuid.uuid4())
 ts=datetime.datetime.now(datetime.timezone.utc)
 d={"client_event_id":cid,"type":typ,"channel":"direct","method":method,"path":path,
    "payload":payload,"enqueued_at":ts.strftime("%Y-%m-%dT%H:%M:%S.%fZ")}
@@ -779,7 +885,7 @@ PY
 # propuesta de épica) y compartir el backoff del lote dejaría los hechos de dominio del slice
 # esperando detrás de una propuesta. El ritmo real de reintento lo marca el ciclo del daemon.
 _runtime_dispatch_direct() {
-  local f rc=0 resp status type path method payload gv server_gv n409 prev_gv stamped reason
+  local f rc=0 resp status type path method payload gv server_gv n409 prev_gv stamped
   for f in "$@"; do
     [ -f "$f" ] || continue
     # [Ronda final] `gv` se reinicia POR ITERACIÓN: es `local` a la función y solo se asigna
@@ -821,17 +927,17 @@ _runtime_dispatch_direct() {
         # escaneo del nombre bajo `set -u` en esta bash — `${type}` lo aísla.
         _runtime_reject_file "$f" "el hub no expone $path (HTTP 404): esta instancia está sin soporte para «${type}» — actualiza el hub y vuelve a proponer" ;;
       409)
-        # [Ronda de arreglo 1, Important 4] El `reason` decide, igual que en `_claim_once`:
-        # un 409 por OTRA causa (propuesta duplicada, conflicto de estado…) no es un grafo
-        # rancio y tratarlo como tal apartaría la propuesta con un diagnóstico falso.
-        reason="$(printf '%s' "$resp" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("reason") or "")' 2>/dev/null)"
-        if [ "$reason" = "stale_graph" ]; then
+        # [Ronda de arreglo 1, Important 4] El cuerpo decide, igual que en `_claim_once`:
+        # un 409 por OTRA causa (client_event_id de otro agregado, conflicto de estado…) no es
+        # un grafo rancio y tratarlo como tal apartaría la propuesta con un diagnóstico falso.
+        # [EP-OR-17] La lectura vive en `runtime_stale_graph_version`, que conoce la forma real
+        # del hub (`detail.error`) además de la plana legacy que este sitio leía a mano.
+        if server_gv="$(runtime_stale_graph_version "$resp")"; then
           # No es un error de contrato: el grafo del hub cambió. Se anota el desfase (lo
           # muestra `status`) y la petición se CONSERVA — el refresco del heartbeat (#61)
           # traerá la versión nueva y el próximo ciclo la re-estampa. Con 3 rechazos seguidos
           # se deja de insistir: a esas alturas no es una carrera, y un bucle silencioso es
           # peor que un rechazo visible.
-          server_gv="$(printf '%s' "$resp" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("graph_version") or "")' 2>/dev/null)"
           runtime_graph_note_stale "$gv" "$server_gv"
           n409="$(_runtime_direct_field "$f" graph_409)"
           case "$n409" in ''|*[!0-9]*) n409=0 ;; esac