@trycore/spec-build-harness 0.13.0 → 0.14.1

package/docs/runtime/guia-modo-dual-y-migracion.md

@@ -55,16 +55,47 @@ Si `--runtime-mode` no se especifica pero sí `--runtime-url`/`--runtime-token`,
 `dual` (nunca `runtime` — el corte directo a `runtime` sin pasar por `dual` no está soportado por
 diseño: es exactamente el "big bang" que el plan de migración evita).
 
-## 4. Activar `dual` en un proyecto ya instalado (`update`)
+## 4. Activar `dual` en un proyecto ya instalado
 
-`trycore-build update` no acepta las flags de runtime directamente hoy — vuelve a correr `init` con
-las mismas flags sobre el proyecto existente; es idempotente (no pisa `build-state.json` ni
-`stack-allowlist.json`, solo añade las credenciales y el modo):
+Este es el camino normal: el proyecto ya lleva el arnés en `legacy` (tiene
+`.claude/.build-harness-version` y su `build-state.json` con historial) y quieres que además
+espeje al hub.
+
+**`trycore-build update` no acepta las flags de runtime.** Vuelve a correr `init` con ellas sobre
+el proyecto existente: `init` detecta la instalación previa y es **idempotente** — no pisa
+`build-state.json` ni `stack-allowlist.json`, solo añade las credenciales y el modo.
 
 ```bash
-trycore-build init --runtime-url "..." --runtime-token "..." --runtime-mode dual
+# 0. Parte de un arnés al día (si vienes de una versión vieja, primero esto)
+npm i -g @trycore/spec-build-harness@latest
+cd /ruta/al/proyecto
+trycore-build update
+
+# 1. Añade las credenciales y activa el espejo
+trycore-build init --runtime-url "https://tu-runtime.example.com" \
+                   --runtime-token "<token-del-ADMIN>" \
+                   --runtime-mode dual
+
+# 2. Comprueba
+trycore-build doctor
+trycore-build status
 ```
 
+El paso 0 importa: las credenciales y el modo se escriben igual, pero los **hooks del cliente
+runtime** (`session-start`, `event-emitter`, `context-sync`, `heartbeat`, `dual-compare`,
+`session-stop`) solo existen desde la 0.9.0. Si el proyecto arrastra una versión anterior, el modo
+queda escrito y **nada lo ejecuta**: sin ese `update` previo el espejo no espeja nada.
+
+> **Salto grande de versión.** `update` refresca assets y schema, nunca tu estado. Si vienes de
+> varias minor por detrás, corre `trycore-build status` después y mira el informe en vez de darlo
+> por bueno: te dirá si la versión instalada quedó sincronizada y si el estado sigue validando.
+
+### ¿Y el historial que ya tienes?
+
+Activar `dual` **no** sube tus slices archivados: el espejo solo cubre lo que ocurra de aquí en
+adelante. Para que el hub conozca el pasado, ver §7 (`trycore-build migrate`). Es opcional — el
+piloto funciona igual sin ello, solo que las proyecciones del servidor empiezan vacías.
+
 ## 5. Verificar que quedó bien
 
 ```bash
@@ -73,19 +104,68 @@ trycore-build status    # resumen + sección "Runtime": conexión, proyección,
 ```
 
 Dentro de una sesión de Claude, `/build:status` da el mismo informe (más `next-step` derivado) y
-`/build:claim [EP-XXX]` reclama la siguiente tarea directamente contra el runtime.
+`/build:claim` reclama la siguiente tarea directamente contra el runtime. **`claim` no acepta épica
+dirigida**: el hub reparte por orden de cola y `claim --epic EP-XXX` falla explícito con `rc 2`
+(issue #39 — el servidor ignoraba el `epic_code` en el cuerpo y entregaba la primera épica de su
+cola como si fuera la pedida, dejando un lease huérfano que solo la consola admin libera). Si
+necesitas dirigir una épica concreta, termina el slice en `dual`, pide al ADMIN apagar el espejo y
+reclama lo que la cola sirva.
 
 ## 6. Qué cambia en el día a día
 
 **Nada que tengas que operar tú a mano.** Las skills (`building-a-slice`, `releasing-a-version`,
 `managing-parallel-front`) conducen exactamente el mismo pipeline; por debajo, en vez de
-leer/escribir `build-state.json` directamente, llaman a `slice-ops.sh`/`release-ops.sh` (13
-subcomandos: `claim`, `gate`, `wiring`, `progress`, `checkpoint`, `submit`, `archive`, `fact`,
-`propose-asset`, `status`, `escalate`, y del lado release `verdict`/`front-integration`) — nunca
+leer/escribir `build-state.json` directamente, llaman a `slice-ops.sh`/`release-ops.sh` — nunca
 arman peticiones a mano. En `dual`, cada transición también se **espeja** al servidor con la
 identidad del fichero (que sigue mandando). Si el espejo falla (red caída, servidor rechaza), el
 trabajo local **nunca se bloquea** — se avisa y queda como discrepancia para el comparador.
 
+`slice-ops.sh` tiene **17 subcomandos** (los conducen las skills; los listamos para que puedas
+leer un log o depurar, no para que los teclees):
+
+| Subcomando | Para qué |
+|---|---|
+| `mode` | imprime `legacy`\|`dual`\|`runtime` |
+| `claim` | reclama trabajo (el hub reparte por orden de cola; sin épica dirigida) |
+| `next-step` | deriva la siguiente acción desde la caché de proyección |
+| `phase` | reporta la fase del pipeline (emite la cadena que falte; idempotente) |
+| `gate` | reporta un veredicto del slice |
+| `submit` · `archive` | entrega y archiva el slice |
+| `wiring` | siembra y actualiza el checklist de cableado |
+| `progress` · `checkpoint` | bitácora y continuidad tras una caída |
+| `fact` | reporta un hecho de proyecto confirmado |
+| `propose-asset` | propone un documento al plano de contexto (lo publica un ADMIN) |
+| `propose-epic` · `epic-status` · `epic-writeback` | proponen una épica, consultan su estado y proyectan la aprobada a `epicas.md` |
+| `status` · `escalate` | informe local del agente y registro de un bloqueo |
+
+Del lado release, `release-ops.sh` añade `verdict` y `front-integration`.
+
+**Códigos de salida** (sobre estos ramifica la prosa de las skills): `0` ok · `2` uso · `3` legacy ·
+`4` sin slice · `5` offline · `6` rechazado · `7` sin trabajo.
+
+### Lo que aportó la 0.14.0
+
+- **El contexto ya no se queda congelado** (#61). El daemon de heartbeat refresca `GET /agent/context`
+  cada `runtime.context_refresh_s` segundos (default **45**; `0` lo desactiva; override
+  `TRYCORE_CONTEXT_REFRESH_S`), **solo en modo `runtime`**. Antes, la caché se hidrataba al arrancar
+  la sesión y en cada `claim` — y el `claim` ocurre una vez por slice, así que una terminal abierta
+  podía trabajar horas contra una foto vieja. Si el refresco falla, la caché anterior **se conserva**
+  y se marca stale (lo dice `/build:status`): quedarse sin proyección dejaría al agente huérfano.
+- **Las épicas se proponen, no se escriben** (#62). En `runtime`, el agente ya no elige el `EP-XXX`:
+  lo propone al hub con **`/build:epic`**, un humano lo aprueba en la consola, el hub asigna la
+  identidad y `/build:epic --check` proyecta la épica aprobada a `docs/03-backlog/epicas.md`. El
+  fichero pasa a ser una **proyección del grafo**, nunca una fuente paralela. La propuesta viaja por
+  un carril de la cola offline, así que sobrevive a quedarte sin red.
+- **Una terminal desactualizada ya no puede hacer daño** (#63). `claim` y la propuesta de épica
+  mandan la versión de grafo que conocen; si está rancia, el hub responde `409` y el cliente
+  refresca y reintenta una vez en vez de fallar. `/build:status` avisa si tu versión va por detrás.
+
+> **Dependencia externa:** las mitades de servidor de #62 y #63 (`trycore-ia-hub#113`, `#114`, `#115`)
+> **todavía no existen**. Contra un hub que no las implementa, `/build:epic` recibe un `404` y aparta
+> la propuesta diciendo «esta instancia está sin soporte», sin reintentos en bucle; y un hub que no
+> versiona el grafo ve exactamente el mismo cuerpo de `claim` de siempre. El refresco de contexto
+> (#61) **sí funciona hoy**: no necesita nada nuevo del servidor.
+
 **El comparador dual** (`hooks/build/dual-compare.sh`, hook `Stop`) corre después de cada turno:
 compara la proyección del servidor contra el fichero local (épica, fase, gates ya resueltos) y, si
 divergen, lo escala vía `/build:escalate` — nunca bloquea el cierre de sesión. Es el instrumento

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

@@ -59,6 +59,15 @@ Reglas del cliente (las implementa `slice-ops.sh claim`, no la prosa de la skill
    (rc 2, sin abrir socket) explicando el protocolo real: terminar el slice en dual → cutover
    admin → reclamar del hub lo que la cola reparta.
 
+**Versión de grafo (#63 / hub#115).** `GET /agent/context` expone `context.graph_version`; el
+cliente la manda en `POST /tasks/next` y en la propuesta de épica **solo si la conoce** (un hub
+que no versiona ve el cuerpo de siempre). Un `409` con `{"reason":"stale_graph","graph_version":
+M}` no es un error: se anota el desfase en `.claude/state/graph-status.json`, se refresca la
+proyección y se reintenta **una vez**; un segundo rechazo sale con un mensaje que nombra el
+desfase y la acción. En el carril directo la versión se estampa **al despachar**, nunca al
+encolar — sellarla al encolar condenaría al 409 a todo despacho diferido —, y tras tres
+rechazos consecutivos la petición se aparta en vez de reintentarse en bucle.
+
 Actos de dominio posteriores (todos por `slice-ops.sh`, ninguno a mano):
 `POST /slices/{id}/verdicts` · `POST /checkpoints` · `POST /slices/{id}/submit` · eventos
 `wiring_*`, `progress_noted`, `slice_archived`, `slice_escalated` y los hechos de
@@ -102,6 +111,32 @@ Offline: sin runtime se trabaja con el último lock; la statusline marca `⚠ st
 - Cota: 5 MB / 72 h — al superarla se descartan primero los eventos evictables (todo tipo fuera de la lista protegida), **nunca** `checkpoint_recorded`, `gate_verdict`, `slice_escalated`, `slice_submitted`, `slice_archived`, `wiring_*`, `project_fact_updated`, `handoff_recorded` ni el propio `telemetry_gap` (nombres del catálogo v2; los alias 0.10.x de los cuatro renombrados siguen protegidos porque la capa de compat los entrega). El descarte se reporta como evento `telemetry_gap` con el payload del catálogo `{dropped, window_h, reason}` (issue #44), coalescido en un único gap mientras la cola siga sobre la cota.
 - Flush forzado en `Stop`: `session-stop.sh` deja el sentinela `outbox/.flush-request`; el daemon `heartbeat.sh` lo consume de forma asíncrona (nunca en el hilo del hook). `trycore-build doctor` **reporta** el tamaño/edad de la cola pero **no** dispara un flush síncrono — sigue sin implementar.
 
+**Carril directo** (`channel: "direct"`). Un fichero de la outbox puede llevar `channel:
+"direct"`, `method` y `path`: entonces no entra en el lote de `POST /events`, se despacha solo a
+su endpoint. Comparte directorio, formato, cota (`RUNTIME_OUTBOX_PROTECTED`) y sentinela de
+flush con la cola de eventos.
+
+**Idempotencia del carril directo — contrato asumido de hub#113.** El cuerpo de cada petición
+del carril directo lleva `client_event_id` (el mismo UUID que nombra el fichero de la outbox) como
+**clave de idempotencia**: el servidor debe tratar dos peticiones con el mismo `client_event_id`
+como **una sola** y devolver el mismo recurso en la segunda, igual que hace `POST /events` con los
+`duplicates[]`. No es opcional. Hay **dos despachadores** posibles sobre la misma cola —el daemon
+de heartbeat y el proceso en primer plano de la skill (`slice-ops.sh propose-epic`)—; el cliente
+los serializa con un mutex de directorio (`.claude/state/.outbox-dispatch.lock`, `mkdir` atómico,
+liberación por edad a los 2 min), pero el mutex es **por repo**: dos worktrees del mismo proyecto,
+o un reintento tras un corte a mitad de respuesta, siguen pudiendo entregar la misma propuesta dos
+veces. Sin deduplicación server-side eso son **dos propuestas** y, al aprobarlas, **dos `EP-XXX`**
+para la misma épica — justo la colisión de numeración que el carril existe para evitar. Un
+`client_event_id` ya presente en el payload del productor **manda** (no se sobrescribe); el resto
+del cuerpo no se toca.
+
+Resultado por petición: `2xx` → acuse en `outbox/acks/<cid>.json`
+y borrado; `404` → **instancia del hub sin soporte**, se aparta a `rejected/` diciéndolo;
+`4xx` (salvo `408`/`429`) → rechazo de contrato, se aparta; `000`/`5xx`/`408`/`429` → se
+conserva y se reintenta en el siguiente ciclo. No agenda backoff propio: es de volumen
+bajísimo y compartir el del lote dejaría los hechos de dominio esperando detrás. La ruta la
+estampa `lib/runtime-ops.sh` al encolar — `runtime-client.sh` no conoce la tabla de endpoints.
+
 ## 6. Declaración de tipos de asset (`asset-types.json` del paquete)
 
 El paquete del plugin declara los tipos de documento que sabe generar. En el registro, el runtime hace upsert idempotente (aditivos auto-publicados; breaking quedan propuestos para un ADMIN):
@@ -146,6 +181,7 @@ agente jamás publica contexto.**
 | `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**). |
 | Reloj local desviado | El cliente usa siempre `expires_at` del servidor, nunca calcula TTL con reloj propio. |
 
 ## 8. Seguridad del cliente
@@ -163,6 +199,13 @@ No existe evento Timer, los hooks son efímeros y un `PostToolUse` throttled no
 - **Muerte**: cuando no queda **ningún** ppid registrado vivo (dos sesiones sobre el mismo repo comparten daemon; cerrar la primera no lo mata). Nunca se cuelga de `Stop` ni de `SessionEnd`.
 - **Deberes por tick** (`TRYCORE_HEARTBEAT_TICK_S`, default 5 s): consumir `outbox/.flush-request` y despachar; cada `lease_ttl_s/3` (valor del servidor, mínimo 10 s), `PUT /leases/renew`. **Sin lease no se apaga**: los eventos de ámbito proyecto (pre-claim) necesitan despachador.
 
+**Deberes por tick** (cadencias independientes): consumir el sentinela de flush y despachar la
+cola; cada `lease_ttl_s/3`, renovar el lease; cada `runtime.context_refresh_s` (default 45 s),
+`GET /agent/context` para refrescar la proyección local. El refresco de contexto es la
+contrapartida cliente de los `nudges` del servidor: el hub ya los emite y el cliente ya los
+normaliza y los pinta — lo que faltaba era que alguien leyera con regularidad. Un refresco
+fallido nunca degrada la caché: se conserva la anterior y se marca `context_stale`.
+
 ## 10. Operaciones de skill (`slice-ops.sh` / `release-ops.sh`)
 
 Las skills son prosa: **no** arman peticiones. Cada acto de dominio pasa por un ejecutable
@@ -185,10 +228,31 @@ modo, valida en local lo que es barato validar y encola lo que no pudo entregar.
 | `slice-ops.sh propose-asset` | `POST …/context/agent-proposals` (§6) |
 | `slice-ops.sh status` | `GET /agent/context` (refresco) + ficheros locales; reporta además `outbox/rejected/` (conteo + tipo y razón del rechazo más reciente, issue #52) |
 | `slice-ops.sh escalate` | evento `slice_escalated {cause}` (gate y fase dentro del texto de la causa; exige slice activo en runtime) |
+| `slice-ops.sh propose-epic --file B` | `POST /projects/{id}/epic-proposals` (carril directo). Propone una épica **sin `EP-XXX`**: la identidad la asigna el hub al aprobar (hub#113). `0` enviada · `5` encolada · `6` rechazada · `3` legacy/dual. Un `epic_code` en el borrador se **ignora**, no se rechaza |
+| `slice-ops.sh epic-status [--id P]` | `GET /projects/{id}/epic-proposals/{P}`. Resuelve el ciclo: `QUEUED` → `PROPOSED` → `APPROVED` (con `epic_code`) / `REJECTED`. Informativo: `rc 0` siempre en runtime |
+| `slice-ops.sh epic-writeback [--id P] [--file F]` | — (local). Escribe en `docs/03-backlog/epicas.md` las épicas ya `APPROVED`, con el código del hub. Mecánico e idempotente: el fichero es proyección del grafo. `--file F` permite otro fichero del backlog (partido en varios), pero **F queda acotado al subárbol `docs/03-backlog/` del proyecto** —`realpath` sobre ambos lados, así que ni symlinks ni `..` escapan— porque los contactos de escritura del arnés en `docs/` son cuatro y acotados (METODOLOGIA §9.2) y este comando promete tocar solo el backlog. Fuera de ahí, `2` con la ruta permitida en el mensaje y **cero escritura**, exista el fichero o no. `0` escribió · `7` nada pendiente · `4` sin fichero · `2` `--file` fuera del carve-out |
 | `release-ops.sh verdict <line> <gate> <estado>` | `POST /releases/{line}/verdicts`; **sin fallback offline** (rc 5 y reintento al reconectar: el agregado `release` no entra por `POST /events`, issue #44) |
 | `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) |
 
+**Forma del borrador de `propose-epic --file`:**
+
+```json
+{
+  "title": "…",
+  "objective": "…",
+  "layer": "foundational|business|technical",
+  "files_scope": ["…"],
+  "depends_on": ["EP-012"],
+  "stories": [{"title": "…", "acceptance_criteria": "…"}]
+}
+```
+
+`title` y `objective` son obligatorios; `layer` por defecto `business` (rc 2 si no es una de las
+tres). Un `epic_code`/`code`/`id` en el borrador **se ignora con aviso**, no se rechaza la
+propuesta — la identidad la asigna el hub al aprobar (hub#113). El normalizador estampa
+`origin: "harness-draft"` antes de encolar.
+
 **Códigos de salida** (contrato con la prosa): `0` ok · `2` uso · `3` modo legacy (o claim en dual)
 · `4` sin slice activo · `5` offline (encolado si el tipo tiene camino por la cola; si no, reintento manual al reconectar) · `6` rechazado por el servidor (no reintentar) ·
 `7` sin trabajo.

package/hooks/build/design-source-guard.sh

@@ -18,7 +18,18 @@ HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$HERE/lib/projection.sh"
 if [ "$(runtime_mode)" = "runtime" ]; then
   CACHE="$(runtime_projection_path)"
-  [ -f "$CACHE" ] || exit 0
+  if [ ! -f "$CACHE" ]; then
+    # auto-arme (sin credenciales) vs desconectado (con credenciales): ver
+    # runtime_disconnected en lib/runtime-client.sh.
+    if runtime_disconnected; then
+      echo "⛔ sin conexión con el hub: hay credenciales del proyecto pero no hay proyección local." >&2
+      echo "   Este agente no sabe qué trabajo tiene asignado, así que no puede escribir código." >&2
+      echo "   Recupérala con \`slice-ops.sh status\` (refresca /agent/context) y reclama con \`/build:claim\`." >&2
+      echo "   Si esto es un worktree: el estado del arnés vive en el clon principal y no viaja al worktree." >&2
+      exit 2
+    fi
+    exit 0
+  fi
   if ! command -v python3 >/dev/null 2>&1; then
     echo "⛔ design-source-guard: python3 no disponible; no puedo verificar el gate de fuente de diseño. Instala python3 (trycore-build doctor)." >&2
     exit 2

package/hooks/build/heartbeat.sh

@@ -18,10 +18,19 @@ set -uo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$HERE/lib/runtime-client.sh"
 source "$HERE/lib/projection.sh"
+source "$HERE/lib/agent-context.sh"
 
 HB_TICK_S="${TRYCORE_HEARTBEAT_TICK_S:-5}"
 case "$HB_TICK_S" in ''|*[!0-9]*) HB_TICK_S=5 ;; esac
 
+# Cadencia del refresco de contexto [#61]. NO es el tick: renovar un lease es barato, pero
+# `GET /agent/context` es una proyección entera del proyecto — a 5 s castigaría al hub sin
+# ganar nada. 45 s es del orden de la latencia con la que un humano aprueba una épica.
+# `0` lo desactiva (vuelta al comportamiento previo a #61).
+HB_CONTEXT_S="${TRYCORE_CONTEXT_REFRESH_S:-}"
+[ -n "$HB_CONTEXT_S" ] || HB_CONTEXT_S="$(config_get runtime.context_refresh_s 45)"
+case "$HB_CONTEXT_S" in ''|*[!0-9]*) HB_CONTEXT_S=45 ;; esac
+
 hb_pidfile()   { echo "$(config_root)/.claude/state/heartbeat.pid"; }
 hb_sessions()  { echo "$(config_root)/.claude/state/heartbeat-sessions.json"; }
 hb_statusfile() { echo "$(config_root)/.claude/state/heartbeat-status.json"; }
@@ -115,7 +124,11 @@ PY
   echo "$n"
 }
 
-# hb_write_status <json> — estado observable del daemon (lo lee statusline-bridge.sh).
+# hb_write_status <fragmento-json> — UPSERT del fragmento sobre el estado observable del
+# daemon (lo lee statusline-bridge.sh y `slice-ops.sh status`). Es merge y no reemplazo
+# desde #61: el fichero lo escriben DOS deberes distintos del tick — la renovación del lease
+# y el refresco de contexto — y con reemplazo el último en escribir borraba el diagnóstico
+# del otro (un refresco correcto tapaba un `lease_lost: true` recién detectado).
 hb_write_status() {
   local body f
   body="$1"
@@ -126,14 +139,22 @@ hb_write_status() {
 import json,sys,os,tempfile
 path,body=sys.argv[1],sys.argv[2]
 try:
-    d=json.loads(body)
+    d=json.load(open(path))
 except Exception:
     d={}
+if not isinstance(d,dict):
+    d={}
+try:
+    frag=json.loads(body)
+except Exception:
+    frag={}
+if isinstance(frag,dict):
+    d.update(frag)
 dirn=os.path.dirname(path) or "."
 fd,tmp=tempfile.mkstemp(dir=dirn,prefix=".heartbeat-status.",suffix=".tmp")
 try:
     with os.fdopen(fd,"w") as out:
-        json.dump(d,out,indent=2)
+        json.dump(d,out,indent=2); out.flush(); os.fsync(out.fileno())
     os.replace(tmp,path)
 except Exception:
     try: os.unlink(tmp)
@@ -168,8 +189,40 @@ hb_renew() {
   esac
 }
 
+# hb_refresh_context — refresca la caché de proyección desde GET /agent/context. Es el ÚNICO
+# camino por el que una terminal ABIERTA se entera de algo nuevo: `session-start.sh` hidrata
+# una vez al arrancar y `slice-ops.sh` solo en claim/status — y el claim ocurre una vez por
+# slice, así que sin esto una sesión larga trabaja horas contra una foto vieja (#61).
+# Solo en modo `runtime`: en legacy|dual el fichero local es primario y el comportamiento no
+# cambia. `agent_context_fetch_and_cache` NUNCA pisa la caché anterior si falla (fail-open);
+# aquí solo se anota el diagnóstico, para que `status` distinga «vieja» de «no se pudo».
+#
+# `last_context_status` es SIEMPRE una cadena. El diagnóstico no es solo un código HTTP
+# (`"write_error"` no lo es) y `"000"` —el valor de «sin red» de `runtime_http_status`— no es
+# un número JSON válido: emitirlo sin comillas rompía el parseo del fragmento entero y
+# `hb_write_status` acababa no escribiendo NADA, ni siquiera el `context_stale: true`.
+hb_refresh_context() {
+  local status rc
+  [ "$(runtime_mode)" = "runtime" ] || return 0
+  agent_context_fetch_and_cache >/dev/null 2>&1
+  rc=$?
+  if [ "$rc" -eq 0 ]; then
+    hb_write_status "{\"context_stale\": false, \"last_context_status\": \"200\", \"last_context_refresh_at\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}"
+    return 0
+  fi
+  # [#61 · ronda final] Un 200 que no se pudo normalizar o escribir NO es un fallo de red:
+  # anotarlo como «último intento: 200» mandaba a mirar el sitio equivocado.
+  if [ "$rc" -eq 2 ]; then
+    status="write_error"
+  else
+    status="$(runtime_http_status)"
+  fi
+  hb_write_status "{\"context_stale\": true, \"last_context_status\": \"$status\"}"
+  return 1
+}
+
 hb_daemon() {
-  local pidf interval ttl last now n
+  local pidf interval ttl last last_ctx now n
   pidf="$(hb_pidfile)"
   mkdir -p "$(dirname "$pidf")"
   printf '%s' "$$" > "$pidf"
@@ -184,6 +237,9 @@ hb_daemon() {
       ;;
   esac
   last=0
+  # `session-start.sh` acaba de hidratar la caché: arrancar el contador AHORA evita un
+  # refresco redundante en el primer tick del daemon.
+  last_ctx="$(date +%s)"
   while :; do
     sleep "$HB_TICK_S"
     n="$(hb_prune_sessions)"
@@ -194,6 +250,10 @@ hb_daemon() {
       runtime_dispatch_outbox >/dev/null 2>&1
     fi
     now="$(date +%s)"
+    if [ "$HB_CONTEXT_S" -gt 0 ] && [ $(( now - last_ctx )) -ge "$HB_CONTEXT_S" ]; then
+      hb_refresh_context
+      last_ctx="$now"
+    fi
     if [ $(( now - last )) -ge "$interval" ]; then
       hb_renew
       runtime_dispatch_outbox >/dev/null 2>&1

package/hooks/build/lib/agent-context.sh

@@ -102,8 +102,12 @@ out = {
         "checkpoint": checkpoint,
     },
     "nudges": nudges,
+    # [#63] `graph_version` viaja junto al manifest_hash: es la foto del BACKLOG (épicas y sus
+    # estados), no la del contexto gobernado. Un hub que no versiona la deja en None y el
+    # cliente sigue funcionando exactamente igual que antes (compatibilidad hacia atrás).
     "context": {"manifest_hash": first(ctx.get("manifest_hash"), raw.get("manifest_hash")),
-                "version": first(ctx.get("version"), raw.get("context_version"))},
+                "version": first(ctx.get("version"), raw.get("context_version")),
+                "graph_version": first(ctx.get("graph_version"), raw.get("graph_version"))},
     "lease": {"expires_at": first(lease.get("expires_at"), raw.get("lease_expires_at")),
               "ttl_s": first(lease.get("ttl_s"), raw.get("lease_ttl_s"))},
 }
@@ -120,20 +124,25 @@ PY
 }
 
 # agent_context_fetch_and_cache — GET /agent/context, normaliza y escribe la caché.
-# rc 0 = caché actualizada · 1 = no se pudo (red, status != 200, respuesta ilegible):
-# en ese caso la caché anterior NO se toca, y los guards siguen operando con ella.
+# rc 0 = caché actualizada · 1 = no se pudo TRAER (red caída, status != 200) · 2 = el hub
+# respondió 200 pero la respuesta no se pudo normalizar o la proyección no se pudo escribir.
+# En ambos fallos la caché anterior NO se toca y los guards siguen operando con ella.
+# [#61 · ronda final] El 2 no es cosmético: con un solo rc de fallo, quien diagnostica después
+# leía `runtime_http_status` == 200 y anunciaba «no se pudo refrescar (último intento: 200)»,
+# que manda a mirar la red cuando el problema está en el disco o en el cuerpo de la respuesta.
+# Todos los llamadores ramifican sobre «rc != 0», así que el código nuevo no cambia su flujo.
 agent_context_fetch_and_cache() {
   local body status tmp norm rc
   body="$(runtime_get "$AGENT_CONTEXT_PATH")"
   status="$(runtime_http_status)"
   [ "$status" = "200" ] || return 1
-  tmp="$(mktemp)" || return 1
+  tmp="$(mktemp)" || return 2
   printf '%s' "$body" > "$tmp"
   norm="$(agent_context_normalize "$tmp")"
   rc=$?
   rm -f "$tmp"
-  [ $rc -eq 0 ] || return 1
-  [ -n "$norm" ] && [ "$norm" != "{}" ] || return 1
-  runtime_projection_write "$norm" || return 1
+  [ $rc -eq 0 ] || return 2
+  [ -n "$norm" ] && [ "$norm" != "{}" ] || return 2
+  runtime_projection_write "$norm" || return 2
   return 0
 }

package/hooks/build/lib/config.sh

@@ -5,8 +5,32 @@
 # config_get. Diseño: fail-open, igual que state-io.sh — nunca lanza.
 
 # config_root — raíz del proyecto consumidor (misma señal que state_path en state-io.sh).
+#
+# Worktrees: el estado del arnés (runtime.credentials, runtime-projection.json,
+# outbox/, build-state.json) está en .gitignore — es secreto y working state, no
+# se versiona — así que NO viaja a un `git worktree add`. Resolviendo la raíz solo
+# por el toplevel, todo agente que arranque en un worktree se queda sin
+# credenciales y opera HUÉRFANO: sin identidad de proyecto, sin lease, sin
+# reportar al hub, y con los guards inhibidos porque su fail-open de auto-arme no
+# distingue "este proyecto no usa el arnés" de "no veo el estado desde aquí".
+# 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.
 config_root() {
-  echo "${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+  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
+  fi
+  echo "$candidate"
 }
 
 # config_get <clave.punteada> <default>