@trycore/spec-build-harness 0.8.5 → 0.11.0

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

@@ -1,43 +1,74 @@
 # Protocolo cliente — Harness v0.9 ↔ Agent Orchestrator Runtime
 
+> **Estado de implementación:** todo el documento refleja lo construido en `hooks/build/` y `src/` (EP-OR-08 sub-slices A-E, código completo en `main`; el corte a `runtime` como único camino sigue pendiente de un piloto real — ver `plan-migracion-harness-v0.9.md` §2.3 y la guía práctica `guia-modo-dual-y-migracion.md`). Las rutas marcadas «contrato del cliente» esperan confirmación contra el OpenAPI real en el re-volcado de EP-OR-13; viven en un solo sitio del cliente bash (`hooks/build/lib/runtime-ops.sh`) y su espejo TS (`src/lib/runtime-client.ts`).
+
 > Contrato del lado cliente. El contrato del lado servidor vive en trycore-ia-hub: `docs/01-prd/anexos/orchestrator-runtime-design.md` (§4 catálogo de eventos, §5 API). Este documento define cómo el harness lo consume: autenticación, mapeo hook→endpoint, sincronización de contexto, cola offline y declaración de tipos de asset.
 
 ## 1. Autenticación y arranque
 
-- **Token de proyecto:** emitido por un ADMIN en el hub, entregado al desarrollador, configurado una vez con `trycore-build init` (se guarda en `.claude/state/runtime.credentials`, fuera de git, `0600`). Todas las llamadas: `Authorization: Bearer <token>`.
-- **Registro:** `POST /agents/register {harness_version, capabilities}` → `{agent_id, project, manifest_hash, poll_interval_s, lease_ttl_s}`. Los intervalos los dicta el servidor (el cliente no los hardcodea). `409 incompatible_version` ⇒ mensaje claro con la versión mínima requerida.
-- **Identidad local:** `agent_id` persiste en `.claude/state/runtime.credentials`; un mismo clon re-registrado reactiva su agente (no crea otro).
+- **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.
 
 ## 2. Mapeo hook → endpoint (la telemetría es del harness, no del modelo)
 
 | Evento Claude Code | Hook v0.9 | Llamada | Notas |
 |---|---|---|---|
-| SessionStart (`startup\|clear\|compact`) | `session-start.sh` | `POST /agents/register` (idempotente) + `GET /agent/context` + sync de contexto (§4) | Inyecta `additionalContext`: slice activo, fase, gates abiertos, wiring failing, resume_hint, nudges, versión de contexto. |
-| PostToolUse (`Edit\|Write\|MultiEdit\|Bash\|Task`) | `event-emitter.sh` | encola → `POST /events` (lote) | **Nunca síncrono en el camino del tool.** Encola en `.claude/state/outbox/` y despacha en background (ver §5). |
-| Timer / PostToolUse throttled | `heartbeat.sh` | `PUT /leases/renew` | Intervalo = `lease_ttl_s / 3` (valor del servidor). |
-| PreCompact / Stop con contexto crítico | `context-monitor.sh` | evento `handoff_recorded {stopped_at, resume_hint}` | Además del aviso local existente. |
-| Stop | `session-stop.sh` | flush de outbox + `GET /nudges` (cacheado) | Renderiza nudges del servidor; sin aritmética local. |
-| PreToolUse (guards) | `gitflow/stack/scaffold/design-source-guard.sh` | **ninguna** (prohibido red en PreToolUse) | Leen archivos sincronizados + caché de proyección local. |
-
-Eventos emitidos por skills (no por hooks): `POST /checkpoints` (tras cada commit significativo), `POST /slices/{id}/verdicts` (al recibir el veredicto de un agente revisor), `POST /slices/{id}/submit` (entrega), `GET /tasks/next` (claim).
+| SessionStart (`startup\|clear\|compact`) | `session-start.sh` | `POST /agents/register` (idempotente, con `asset_types`) + `GET /agent/context` + `context-sync.sh` (§4) + aseguramiento del daemon | Escribe la **caché de proyección normalizada** (`.claude/state/runtime-projection.json`). No inyecta contexto: el render lo hace `load-build-state.sh`, que corre después en el mismo evento. |
+| SessionStart (mismo matcher) | `load-build-state.sh` | **ninguna** | Renderiza `additionalContext` desde la caché en modo `runtime`; en `legacy\|dual` sigue leyendo `build-state.json`. |
+| PostToolUse (`Bash\|Edit\|Write\|MultiEdit\|Task`) | `event-emitter.sh` | **ninguna** | Solo hace la comprobación barata del daemon (stat del pidfile). Desde el issue #44 **no encola nada**: `tool_use_recorded` no existe en el catálogo v2 del hub y era ruido garantizado en `rejected/`; la telemetría de uso queda suspendida hasta que el equipo del hub decida añadir el tipo. |
+| — (daemon, no hook) | `heartbeat.sh --daemon` | `PUT /leases/renew` + `POST /events` | Singleton por repo con registro de ppids de sesión; late cada `lease_ttl_s/3` (valor del servidor) y despacha la cola mientras viva. Ver §9. |
+| — (invocado, no registrado) | `context-sync.sh` | `GET …/context/manifest`, `GET …/context/files?path=…&sha256=…`, `POST /context/synced` | Lo llama `session-start.sh` y, desde el sub-slice C, las skills antes de reclamar. |
+| PreCompact / PostToolUse / Stop | `context-monitor.sh` | encola `handoff_recorded {note, resume_hint, stopped_at}` | En `runtime` el handoff **solo** es evento (no se escribe el fichero); en `dual` se escribe el fichero **y** se emite; en `legacy`, solo el fichero. `handoff_recorded` es de ámbito **slice**: solo se encola con `slice_id` conocido (misma guardia que `event-emitter.sh`); en `dual`, como no hay claim vía runtime, `active_slice` normalmente no llega por `/agent/context` y el evento no se emite (solo queda el fichero). |
+| Stop | `build-gate-check.sh`, `reflect-nudge.sh`, `release-gate-nudge.sh` | **ninguna** | Renderizan los `nudges[]` que trajo `GET /agent/context` (no existe endpoint `/nudges` para agentes: los nudges viajan en el contexto de agente). En `legacy\|dual` conservan su aritmética local. |
+| Stop | `session-stop.sh` | **ninguna** | Deja `outbox/.flush-request` y asegura el daemon: el flush lo ejecuta el daemon, no el hook. |
+| PreToolUse (guards) | `gitflow/stack/scaffold/design-source-guard.sh` | **ninguna** (prohibido red en PreToolUse) | Leen los assets sincronizados y la caché de proyección; bloquean offline y marcan `⚠ stale`. `gitflow-guard` resuelve el repo del **comando** (`git -C`, `cd … &&`), no el de la sesión. |
+
+Eventos emitidos por skills (no por hooks) — sub-slice C: `POST /checkpoints`, `POST /slices/{id}/verdicts`, `POST /slices/{id}/submit`, `POST /tasks/next` (claim: **siempre POST**, el GET no acepta el reporte de hashes).
 
 ## 3. Claim (el corazón del pull)
 
 ```
-GET /tasks/next
-  200 → {slice_id, epic, phase, next_step, branch_base, acceptance_refs,
-         openspec_change, lease: {ttl_s, expires_at}, manifest_hash,
-         checkpoint: {branch, commit_sha} | null}
+POST /tasks/next   {context_hashes: {"<path>": "<sha256>", …}}   // dict[str,str]; {} = reporta vacío;
+                                                                 // valor "" = fichero ilegible (nunca null)
+  200 → {slice_id, epic_code, epic_title, stories[], files_scope, docs_ref, phase, gates,
+         branch_base, openspec_change, manifest_hash,
+         lease: {ttl_s, expires_at}, checkpoint: {branch, commit_sha} | null}
   204 → sin trabajo disponible (la skill lo comunica y termina limpio)
-  409 → carrera perdida (otro agente reclamó primero): reintentar una vez
+  409 → se distingue por el CUERPO, no por el status (`reason`):
+        drift | contention          → re-sincronizar contexto y reintentar UNA vez
+        context_unresolvable        → no reintentar; se resuelve en el hub
+        cross_project               → no reintentar; queda auditado en el servidor
 ```
 
-Reglas del cliente:
-
-1. Antes de trabajar: verificar `manifest_hash` contra el lock (§4); sincronizar si difiere. **No se abre trabajo con contexto viejo.**
-2. Si `checkpoint != null`: hacer checkout/pull de la rama y **continuar desde el checkpoint, jamás reiniciar** (recuperación de otro agente caído).
-3. En el claim se reportan los sha256 locales efectivos de los archivos gobernados (allowlist, policy, rules) — el servidor detecta drift/manipulación local.
-4. Un agente mantiene **un solo** slice activo; `GET /tasks/next` con lease vigente devuelve el mismo slice (idempotencia).
+**Siempre POST**: el `GET /tasks/next` no acepta el reporte de hashes (regla 3), así que el
+cliente no lo usa para reclamar.
+
+Reglas del cliente (las implementa `slice-ops.sh claim`, no la prosa de la skill):
+
+1. Antes de trabajar: `context-sync.sh <manifest_hash>` (§4). **No se abre trabajo con contexto viejo.**
+2. Si `checkpoint != null`: checkout de esa rama y **continuar desde el checkpoint, jamás reiniciar**
+   (recuperación de otro agente caído).
+3. En el claim se reportan los **sha256 locales efectivos** de los archivos gobernados del lock —
+   se hashea el fichero real, nunca se repite el sha del lock: repetirlo haría el drift indetectable.
+4. Un agente mantiene **un solo** slice activo; reclamar con lease vigente devuelve el mismo slice.
+5. Modo `dual`: **no se reclama** (el fichero decide el slice, spec §6.1) — el subcomando devuelve
+   rc 3. Modo `legacy`: no hay red, rc 3.
+6. **No existe claim dirigido**: `TasksNextIn` no acepta `epic_code` (pydantic ignoraría el campo y
+   la cola repartiría otra épica — incidente del primer piloto, issue #39). `claim --epic` falla explícito
+   (rc 2, sin abrir socket) explicando el protocolo real: terminar el slice en dual → cutover
+   admin → reclamar del hub lo que la cola reparta.
+
+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
+proyecto **máquina** (`project_kind`, `harness_phase`, `foundation`) como
+`project_fact_updated {fact, value, source: "AGENT"}` — el único tipo del catálogo v2 para hechos
+(issue #38). Los hechos **humanos** (`scaffold_confirmed`, `design_source_*`) NO viajan por la
+superficie de agente: se fijan tras el PDP por `PATCH /orchestrator/projects/{project_id}`
+(consola admin); `slice-ops fact` los rechaza en runtime/dual con rc 6. Outer loop, por
+`release-ops.sh`: `POST /releases/{line}/verdicts` y
+`POST /fronts/{front_id}/members/{agent_key}/integration`.
 
 ## 4. Sincronización de contexto (content-addressed)
 
@@ -51,22 +82,24 @@ Lockfile: `.claude/state/context.lock`
 }
 ```
 
-Algoritmo (`context-sync.sh`, corre en SessionStart y pre-claim):
+Algoritmo (`context-sync.sh`; lo invoca `session-start.sh` y, en el sub-slice C, las skills pre-claim):
 
-1. Comparar `manifest_hash` esperado (del registro o del claim) con el del lock. Igual ⇒ fin (costo: comparación de strings).
-2. Distinto ⇒ `GET /projects/{id}/context/manifest`; diff por `sha256` archivo a archivo; `GET /context/files/{path}?sha256=…` **solo** de los cambiados (ETag inmutable ⇒ cacheable).
-3. Escritura atómica (`mktemp` + `os.replace`, patrón ya probado en v0.8.1) sobre los destinos gobernados: `config/`, `rules/`, bloques marcados de `CLAUDE.md` (vía `markers.ts`), `docs-cache/` para `DOC`.
-4. Actualizar el lock; emitir `context_synced {from_hash, to_hash, files_changed[]}`; aviso de una línea al usuario (`⬆ contexto v13 → v14: allowlist (+2), PRD §4`).
+1. Comparar el `manifest_hash` esperado (de `/agent/context`, o el persistido en `runtime.credentials`) con el del lock. Igual ⇒ fin (costo: comparación de strings).
+2. Distinto ⇒ `GET /projects/{id}/context/manifest`; diff por `sha256` archivo a archivo; `GET /projects/{id}/context/files?path=…&sha256=…` **solo** de los cambiados (query params, no path params).
+3. **Destinos gobernados por este canal:** `config/`, `rules/` y `docs-cache/`, siempre bajo `.claude/`. Cualquier entrada absoluta, con `..` o fuera de esos prefijos se **rechaza sin escribir** y se lista como «no aplicada» — incluidos los bloques marcados de `CLAUDE.md`, que necesitarían integrar `markers.ts` y **aún no está implementado**. Escritura atómica (`mkstemp` + `os.replace`).
+4. El lock **solo** sella el hash nuevo si se aplicaron TODOS los archivos gobernados del plan; si la convergencia fue parcial, el lock se queda en el hash anterior y la próxima sesión reintenta. Después: `POST /context/synced {from_hash, to_hash, files_changed[]}` (endpoint propio, la única señal sin `slice_id`; `422` ⇒ manifiesto desconocido, no se reintenta) y aviso de una línea al usuario.
 5. **Prohibido** editar a mano archivos gobernados: el sync los sobreescribe y el drift se reporta. El cambio legítimo se hace en el hub (propuesta→publicación).
 
-Offline: sin runtime, se trabaja con el último lock; la statusline marca `⚠ stale`; al reconectar, sync antes del siguiente claim.
+Offline: sin runtime se trabaja con el último lock; la statusline marca `⚠ stale`; al reconectar, sync antes del siguiente claim.
 
 ## 5. Cola offline de eventos (`.claude/state/outbox/`)
 
-- Un archivo JSON por lote, con `client_event_id` (UUID) por evento ⇒ **idempotencia server-side** (reintentos seguros).
-- Despacho en background con backoff (1 s → 5 s → 30 s → 5 min, tope); orden FIFO por agregado.
-- Cota: 5 MB / 72 h — al superarla se descartan primero los eventos de telemetría fina (PostToolUse), **nunca** checkpoints, veredictos ni submits; el descarte se reporta como evento `telemetry_gap` al reconectar.
-- Flush forzado en Stop y en `trycore-build doctor`.
+- Un archivo JSON por evento (no por lote — `runtime_enqueue_event`), con `client_event_id` (UUID) ⇒ **idempotencia server-side** (reintentos seguros). El despacho (`runtime_dispatch_outbox`) sí agrupa en un único `POST /events` por invocación, con el sobre que el hub exige: `{"events": [{client_event_id, event_type, payload, slice_id?}]}` — la clave interna `type` de los ficheros de la outbox se traduce a `event_type` **al armar el cuerpo** (el formato en disco no cambia; ficheros encolados por 0.10.x drenan sin migración). El ack real del hub es `{accepted[], duplicates[], rejected[{client_event_id, reason}]}` (issue #37).
+- **Capa de compat de nombres/payloads en el mismo punto de salida** (issue #44): los productores encolan los nombres del **catálogo v2** del hub (`gate_verdict`, `checkpoint_recorded`, `slice_escalated`, `progress_noted`), pero los ficheros 0.10.x con los nombres viejos (`verdict_reported`, `checkpoint_created`, `escalation_raised`, `progress_note_recorded`) drenan traducidos — tipo **y** claves de payload (`status`→`verdict` en mayúscula, `note`→`summary`, `reason/gate/phase`→`cause`) — sin migración. Los tipos **sin equivalente** en el catálogo (`tool_use_recorded`, `branch_drift`, `front_integration_reported`) se apartan localmente a `outbox/rejected/` sin gastar red.
+- **Un 4xx no es red caída**: un 4xx del lote (salvo 408/429) o un elemento en `rejected[]` del ack **no se reintenta** — el fichero se mueve a `outbox/rejected/` con la razón loggeada y se avisa. Solo 408/429/5xx/corte de red conservan la cola con backoff (fail-open intacto).
+- Despacho en background con backoff persistido (`1 s → 5 s → 30 s → 5 min`, tope; el estado vive en `outbox/.dispatch-state.json` y sobrevive entre invocaciones de hooks distintos). Orden FIFO global — el agrupado por-agregado nace con el catálogo de eventos (sub-slice C).
+- 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.
 
 ## 6. Declaración de tipos de asset (`asset-types.json` del paquete)
 
@@ -96,7 +129,12 @@ El paquete del plugin declara los tipos de documento que sabe generar. En el reg
 }
 ```
 
-Las skills generadoras producen la instancia y la **proponen**: `POST /projects/{id}/context/proposals {type_key, path, frontmatter, body}` — validada server-side contra el `frontmatter_schema`; la publica un ADMIN en el hub. Un agente jamás publica contexto.
+Las skills generadoras producen la instancia y la **proponen** por la superficie de **agente**:
+`POST /projects/{project_id}/context/agent-proposals {path, type_key, content}` — validada
+server-side contra el `frontmatter_schema`; la publica un ADMIN en el hub. La superficie humana
+`…/context/proposals` **no** la usa el arnés. Comando: `slice-ops.sh propose-asset --type-key K
+--path P --content-file F` (`rc 6` si el contenido no valida contra el schema del tipo). **Un
+agente jamás publica contexto.**
 
 ## 7. Errores y degradación (tabla normativa)
 
@@ -106,11 +144,58 @@ Las skills generadoras producen la instancia y la **proponen**: `POST /projects/
 | `409` en claim | Un reintento inmediato; luego informar "otro agente tomó la tarea" y pedir la siguiente. |
 | `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. |
-| `410` en lease (expirado durante trabajo largo) | El slice pudo ser re-entregado: detener, hacer checkpoint local, re-claim (puede devolver el mismo slice si nadie lo tomó). |
+| `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. |
 | Reloj local desviado | El cliente usa siempre `expires_at` del servidor, nunca calcula TTL con reloj propio. |
 
 ## 8. Seguridad del cliente
 
-- El token vive solo en `.claude/state/runtime.credentials` (gitignoreado, `0600`); nunca en `settings.json` ni en el repo — no repetir el incidente de rutas/credenciales de máquina fosilizadas en `settings.json`.
+- El token vive solo en `.claude/state/runtime.credentials` (`0600`, protegido en `.gitignore` desde `init`); nunca en `settings.json` ni en el repo — no repetir el incidente de rutas/credenciales de máquina fosilizadas en `settings.json`.
 - El harness no envía código fuente al runtime: solo referencias git, hashes, veredictos y metadatos (los payloads se validan contra schema; el servidor rechaza payloads sobredimensionados).
 - `trycore-build doctor` verifica: token válido, reloj razonable, lock fresco, outbox drenando, hashes sin drift.
+
+## 9. Daemon de heartbeat (ciclo de vida)
+
+No existe evento Timer, los hooks son efímeros y un `PostToolUse` throttled no late durante una tool call larga. Por eso el latido es un daemon:
+
+- **Singleton por repo**: `.claude/state/heartbeat.pid` + `.claude/state/heartbeat-sessions.json` (ppids de las sesiones interesadas). El arranque se serializa con un mutex de directorio (`mkdir`, atómico), con liberación por edad si queda huérfano.
+- **Relanzamiento**: cada `SessionStart` registra su ppid y relanza si el pidfile está muerto; cada `PostToolUse` repite la comprobación barata (stat + `kill -0`, sin red). Un `kill -9` del daemon se detecta en el siguiente tool use.
+- **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.
+
+## 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
+instalado junto a los hooks —invocado, no registrado, igual que `context-sync.sh`— que decide por
+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 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 gate <g> <pass\|fail\|na>` | `POST /slices/{id}/verdicts` (`{gate, verdict: PASS\|FAIL, evidence}`); offline → evento `gate_verdict`. `na` **no viaja**: el catálogo no lo admite (aviso local, rc 0, issue #44) |
+| `slice-ops.sh wiring seed\|update` | eventos `wiring_checklist_seeded` (items `{item_id, kind, ref}`, sin `status`) / `wiring_item_updated` |
+| `slice-ops.sh progress` | evento `progress_noted` (evictable) |
+| `slice-ops.sh checkpoint` | `POST /checkpoints` (`summary`, no `note`); offline → evento `checkpoint_recorded {branch, commit_sha, summary}` |
+| `slice-ops.sh submit` | `POST /slices/{id}/submit`; offline → evento `slice_submitted` con payload `{}` (el catálogo no admite campos) |
+| `slice-ops.sh archive` | evento `slice_archived` con payload `{}` y `slice_id` (siempre por cola, idempotente) |
+| `slice-ops.sh fact …` | hechos máquina → evento `project_fact_updated` (sin `slice_id`); hechos humanos → rc 6 con remisión al PATCH admin (§3) |
+| `slice-ops.sh propose-asset` | `POST …/context/agent-proposals` (§6) |
+| `slice-ops.sh status` | `GET /agent/context` (refresco) + ficheros locales |
+| `slice-ops.sh escalate` | evento `slice_escalated {cause}` (gate y fase dentro del texto de la causa; exige slice activo en runtime) |
+| `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) |
+
+**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.
+
+**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.
+
+**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.

package/hooks/build/build-gate-check.sh

@@ -3,6 +3,27 @@
 # AUTO-ARME: inerte mientras no exista package.json.
 # No bloquea: al cerrar el turno, avisa si hay un slice activo con gates abiertos.
 set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/lib/projection.sh"
+
+# [EP-OR-08-B] En runtime la aritmética de gates vive en el servidor: este hook solo
+# RENDERIZA lo que el claim/proyección ya dice. Nunca bloquea (Stop hook, exit 0 siempre).
+if [ "$(runtime_mode)" = "runtime" ]; then
+  if [ -n "$(projection_get active_slice.slice_id "")" ]; then
+    abiertos="$(projection_get active_slice.gates '{}' | python3 -c 'import json,sys
+try: g=json.load(sys.stdin)
+except Exception: g={}
+print(", ".join(k for k,v in g.items() if v is False))' 2>/dev/null)"
+    if [ -n "$abiertos" ]; then
+      epica="$(projection_get active_slice.epic_code '?')"
+      hus="$(projection_get active_slice.hus '[]' | tr -d '[]"')"
+      fase="$(projection_get active_slice.phase '?')"
+      echo "build-gate-check: slice $epica [${hus:-—}] en fase '$fase' con gates abiertos: $abiertos." >&2
+      echo "   No archives ni abras PR hasta cerrarlos (ver building-a-slice / dod.md)." >&2
+    fi
+  fi
+  exit 0
+fi
 
 ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
 [ -f "$ROOT/package.json" ] || exit 0

package/hooks/build/context-monitor.sh

@@ -1,11 +1,20 @@
 #!/usr/bin/env bash
 # context-monitor.sh — PostToolUse|PreCompact|Stop. Lee el puente, aplica umbrales,
-# inyecta additionalContext y (en critical) escribe handoff. Fail-open.
+# inyecta additionalContext y en `critical` registra el handoff. Fail-open.
+# [EP-OR-08-B] Comportamiento por modo:
+#   - legacy: v0.8.5 exacto (handoff escrito en build-state.json).
+#   - dual:   igual + el mismo handoff se emite como evento handoff_recorded (espejo).
+#   - runtime: NO se escribe el fichero; el handoff es SOLO el evento, y el guard
+#     once-per-sesión vive en una marca local (.claude/state/.handoff-<session_id>).
 set -uo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$HERE/lib/state-io.sh"
+source "$HERE/lib/runtime-client.sh"
+source "$HERE/lib/projection.sh"
 payload="$(cat)"; command -v python3 >/dev/null 2>&1 || exit 0
 
+MODE="$(runtime_mode)"
+[ "$MODE" != "runtime" ] && source "$HERE/lib/state-io.sh"
+
 read -r SID EVT <<<"$(printf '%s' "$payload" | python3 -c '
 import json,sys
 try: p=json.load(sys.stdin)
@@ -21,11 +30,27 @@ BRIDGE="${TMPDIR:-/tmp}/claude-ctx-$sanitized_sid.json"
 
 WARN="$(config_get context.warning_pct 35)"; CRIT="$(config_get context.critical_pct 25)"
 STALE="$(config_get context.stale_seconds 60)"; AUTO="$(config_get context.auto_checkpoint false)"
-STATE="$(state_path)"
 
-python3 - "$BRIDGE" "$WARN" "$CRIT" "$STALE" "$EVT" "$STATE" "$AUTO" <<'PY' 2>/dev/null || true
+if [ "$MODE" = "runtime" ]; then
+  STATE=""
+  MARK="$(config_root)/.claude/state/.handoff-$sanitized_sid"
+  HINT="$(projection_get active_slice.wiring_failing '[]' | python3 -c 'import json,sys
+try: w=json.load(sys.stdin)
+except Exception: w=[]
+ids=[str(i.get("item_id")) for i in w[:6] if i.get("item_id")]
+print("cablear: "+", ".join(ids) if ids else "")' 2>/dev/null)"
+  [ -n "$HINT" ] || HINT="$(projection_get active_slice.resume_hint "")"
+else
+  STATE="$(state_path)"
+  MARK=""
+  HINT=""
+fi
+mkdir -p "$(config_root)/.claude/state"
+EVENT_OUT="$(mktemp)" || exit 0
+
+python3 - "$BRIDGE" "$WARN" "$CRIT" "$STALE" "$EVT" "$STATE" "$AUTO" "$MODE" "$EVENT_OUT" "$MARK" "$HINT" <<'PY' 2>/dev/null || true
 import json,sys,os,time,tempfile
-bridge,warn,crit,stale,evt,state,auto=sys.argv[1:8]
+bridge,warn,crit,stale,evt,state,auto,mode,event_out,mark,hint=sys.argv[1:12]
 warn,crit,stale=int(warn),int(crit),int(stale)
 try: b=json.load(open(bridge))
 except Exception: sys.exit(0)
@@ -34,18 +59,21 @@ rem=b.get("remaining_pct",100)
 sev = "critical" if rem<=crit else ("warning" if rem<=warn else None)
 if not sev: sys.exit(0)
 
-# ¿slice activo? handoff solo en critical y una vez por sesión.
-recorded=False
-if sev=="critical" and os.path.exists(state):
+iso=time.strftime("%Y-%m-%dT%H:%M:%SZ",time.gmtime())
+recorded=False      # handoff persistido en el fichero (legacy|dual)
+emit=False          # handoff que hay que encolar como evento (dual|runtime)
+resume=hint or "revisar progreso y continuar"
+
+if sev=="critical" and mode!="runtime" and state and os.path.exists(state):
     try:
         d=json.load(open(state)); s=d.get("active_slice")
         if s:
             sc=s.setdefault("session_continuity",{})
             if not sc.get("critical_recorded"):
-                iso=time.strftime("%Y-%m-%dT%H:%M:%SZ",time.gmtime())
                 sc["stopped_at"]=f"context exhaustion at {rem}% ({iso})"
                 failing=[w["id"] for w in (s.get("wiring_checklist") or []) if w.get("status")=="failing"]
-                sc["resume_hint"]=("cablear: "+", ".join(failing[:6])) if failing else "revisar progreso y continuar"
+                resume=("cablear: "+", ".join(failing[:6])) if failing else "revisar progreso y continuar"
+                sc["resume_hint"]=resume
                 sc["critical_recorded"]=True
                 sc["auto_continue"]=(auto=="true")
                 s.setdefault("progress_log",[]).append(
@@ -60,21 +88,60 @@ if sev=="critical" and os.path.exists(state):
                     except OSError: pass
                     raise
     except Exception: pass
+    if recorded and mode=="dual":
+        emit=True
+elif sev=="critical" and mode=="runtime":
+    # El guard once-per-sesión no puede vivir en el fichero (no lo hay): marca local.
+    if mark and not os.path.exists(mark):
+        try:
+            with open(mark,"w") as m: m.write(iso)
+            emit=True
+        except Exception:
+            emit=False
 
+if emit:
+    try:
+        with open(event_out,"w") as out:
+            json.dump({"note":f"handoff auto a {rem}% de contexto restante",
+                       "resume_hint":resume,
+                       "stopped_at":f"context exhaustion at {rem}% ({iso})"},out,ensure_ascii=False)
+    except Exception:
+        pass
+
+transition = recorded or emit
 if sev=="warning":
     msg=(f"⚠️ Contexto al {rem}% restante. Acércate a un punto natural de corte "
          "(fin de fase/gate). No inicies trabajo complejo nuevo.")
 else:
-    tail=(" Handoff escrito en build-state.json (session_continuity)." if recorded else "")
+    if mode=="runtime":
+        tail=(" Handoff registrado en el runtime (handoff_recorded)." if emit else "")
+        origen="El estado vive en el runtime;"
+    else:
+        tail=(" Handoff escrito en build-state.json (session_continuity)." if recorded else "")
+        origen="El estado ya vive en build-state.json;"
     cont=(" auto_checkpoint=ON: continúa en sesión fresca." if auto=="true" else
           " Avisa al usuario para reiniciar en un punto natural.")
-    msg=(f"🛑 Contexto CRÍTICO al {rem}% restante.{tail} El estado ya vive en build-state.json;"
+    msg=(f"🛑 Contexto CRÍTICO al {rem}% restante.{tail} {origen}"
          f" no reescribas handoff manual.{cont}")
 # En 'Stop', inyectar additionalContext RE-LANZA el turno (re-prompt): repetirlo en cada
 # intento de cierre entra en bucle hasta el tope CLAUDE_CODE_STOP_HOOK_BLOCK_CAP (=9→override).
 # Por eso en 'Stop' re-lanzamos como MUCHO una vez por sesión y solo en la TRANSICIÓN a crítico
-# (recorded=True, el instante en que se graba el handoff). 'warning' nunca inyecta en 'Stop'
-# (el nudge solo sirve mientras se trabaja). Fuera de 'Stop' se inyecta con normalidad.
-if evt=="Stop" and not (sev=="critical" and recorded): sys.exit(0)
+# (el instante en que se graba/emite el handoff). 'warning' nunca inyecta en 'Stop'.
+if evt=="Stop" and not (sev=="critical" and transition): sys.exit(0)
 print(json.dumps({"hookSpecificOutput":{"hookEventName":evt,"additionalContext":msg}}))
 PY
+
+# El evento se encola FUERA del bloque python: encolar es competencia del cliente bash
+# (runtime_enqueue_event), y así el stdout del hook queda limpio pase lo que pase.
+# handoff_recorded es de ámbito slice: los eventos de ámbito slice llevan slice_id, sin
+# slice_id conocido NO se encolan (el servidor los rechazaría elemento a elemento) — misma
+# guardia que event-emitter.sh. En `dual` es el caso NORMAL, no el borde: dual no reclama
+# vía runtime, así que /agent/context no trae active_slice y sin esta guardia el evento se
+# encolaba sin slice_id, quedando como poison pill en RUNTIME_OUTBOX_PROTECTED si el
+# servidor rechazaba el lote entero.
+SLICE_ID_HANDOFF="$(projection_get active_slice.slice_id "")"
+if [ -s "$EVENT_OUT" ] && [ "$MODE" != "legacy" ] && [ -n "$SLICE_ID_HANDOFF" ]; then
+  runtime_enqueue_event "handoff_recorded" "$(cat "$EVENT_OUT")" "$SLICE_ID_HANDOFF" >/dev/null 2>&1
+fi
+rm -f "$EVENT_OUT"
+exit 0

package/hooks/build/context-sync.sh

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# context-sync.sh — sincronización de contexto content-addressed [EP-OR-08-B]
+# (protocolo-cliente-runtime §4). NO es un hook registrado: lo invoca session-start.sh y,
+# desde el sub-slice C, las skills antes de reclamar.
+#   uso: context-sync.sh [manifest_hash_esperado]
+# Fail-open: sin runtime, sin python3 o con manifiesto ilegible sale 0 y deja el lock
+# anterior intacto — se sigue trabajando con el último contexto sincronizado.
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/lib/runtime-client.sh"
+
+MODE="$(runtime_mode)"
+[ "$MODE" = "legacy" ] && exit 0
+command -v python3 >/dev/null 2>&1 || exit 0
+
+EXPECTED="${1:-}"
+[ -n "$EXPECTED" ] || EXPECTED="$(runtime_field manifest_hash)"
+CURRENT="$(runtime_lock_manifest_hash)"
+[ -n "$EXPECTED" ] && [ "$EXPECTED" = "$CURRENT" ] && exit 0
+
+PID="$(runtime_field project_id)"
+[ -n "$PID" ] || exit 0
+
+MANIFEST="$(runtime_get "/projects/$PID/context/manifest")"
+[ "$(runtime_http_status)" = "200" ] || exit 0   # offline: se sigue con el lock viejo
+
+ROOT="$(config_root)"
+WORK="$(mktemp -d)" || exit 0
+trap 'rm -rf "$WORK"' EXIT
+printf '%s' "$MANIFEST" > "$WORK/manifest.json"
+
+# Validación temprana: el manifiesto debe parsear como objeto JSON con un 'manifest_hash'
+# no vacío. Un body no-JSON, un array, o una página de error de proxy servida con status
+# 200 se descartan AQUÍ, antes de planificar/descargar/sellar nada — el lock existente
+# queda intacto y no se emite context/synced con un hash falso.
+NEWHASH="$(python3 -c '
+import json,sys
+try:
+    d=json.load(open(sys.argv[1]))
+    print(d.get("manifest_hash","") if isinstance(d,dict) else "")
+except Exception:
+    print("")
+' "$WORK/manifest.json" 2>/dev/null)"
+[ -n "$NEWHASH" ] || exit 0
+
+# Plan de descarga: una línea "path<TAB>sha256" por archivo GOBERNADO que cambió.
+# Las rutas se validan AQUÍ (antes de tocar disco): solo config/, rules/ y docs-cache/,
+# nunca absolutas, nunca con "..". Un manifiesto hostil o con una entrada de destino no
+# gobernado (CLAUDE.md, que necesita markers.ts — sub-slice D) no escribe nada: se lista
+# como "no aplicado" y NO impide converger el hash.
+python3 - "$WORK/manifest.json" "$(runtime_lock_path)" "$WORK/skipped.txt" > "$WORK/plan.tsv" <<'PY' 2>/dev/null
+import json,sys,posixpath
+ALLOWED_PREFIXES=("config/","rules/","docs-cache/")
+try:
+    man=json.load(open(sys.argv[1]))
+except Exception:
+    sys.exit(0)
+try:
+    lock=json.load(open(sys.argv[2]))
+except Exception:
+    lock={}
+have={}
+for f in (lock.get("files") or []):
+    if isinstance(f,dict) and f.get("path"):
+        have[f["path"]]=f.get("sha256")
+skipped=[]
+for f in (man.get("files") or []):
+    if not isinstance(f,dict):
+        continue
+    path=f.get("path") or ""
+    sha=f.get("sha256") or ""
+    if (not path or not sha or path.startswith("/") or ".." in path.split("/")
+            or path != posixpath.normpath(path)
+            or not path.startswith(ALLOWED_PREFIXES)):
+        skipped.append(path or "(sin ruta)")
+        continue
+    if have.get(path) == sha:
+        continue
+    sys.stdout.write(path+"\t"+sha+"\n")
+sys.stdout.flush()
+try:
+    with open(sys.argv[3],"w") as out:
+        for s in skipped:
+            out.write(s+"\n")
+except Exception:
+    pass
+PY
+
+# Si el plan no se generó (python falló), se trata como plan vacío: nada que descargar,
+# nada que sellar. La redirección nunca debe fallar por fichero ausente.
+[ -f "$WORK/plan.tsv" ] || : > "$WORK/plan.tsv"
+plan=()
+while IFS= read -r line; do
+  [ -n "$line" ] && plan+=("$line")
+done < "$WORK/plan.tsv"
+
+applied=0
+planned=${#plan[@]}
+if [ "$planned" -gt 0 ]; then
+  for line in "${plan[@]}"; do
+    # Campos separados por TAB. Se parten con `cut` (delimitador por defecto = tabulador)
+    # en vez de expansión de parámetros: un tabulador literal dentro de ${…%%…} es
+    # invisible y cualquier editor que lo convierta en espacios rompería el parseo en
+    # silencio, dejando rutas con el sha256 pegado.
+    rel="$(printf '%s' "$line" | cut -f1)"
+    sha="$(printf '%s' "$line" | cut -f2)"
+    enc="$(python3 -c 'import sys,urllib.parse;print(urllib.parse.quote(sys.argv[1],safe=""))' "$rel" 2>/dev/null)"
+    [ -n "$enc" ] || continue
+    body="$(runtime_get "/projects/$PID/context/files?path=$enc&sha256=$sha")"
+    [ "$(runtime_http_status)" = "200" ] || continue
+    printf '%s' "$body" > "$WORK/blob.json"
+    if python3 - "$WORK/blob.json" "$ROOT/.claude/$rel" <<'PY' 2>/dev/null
+import json,sys,os,tempfile
+blob_path,dest=sys.argv[1],sys.argv[2]
+raw=open(blob_path,encoding="utf-8",errors="replace").read()
+try:
+    d=json.loads(raw)
+    content=d["content"] if isinstance(d,dict) and "content" in d else raw
+except Exception:
+    content=raw
+if not isinstance(content,str):
+    content=json.dumps(content,indent=2,ensure_ascii=False)
+dirn=os.path.dirname(dest) or "."
+os.makedirs(dirn,exist_ok=True)
+fd,tmp=tempfile.mkstemp(dir=dirn,prefix=".ctx-sync.",suffix=".tmp")
+try:
+    with os.fdopen(fd,"w") as out:
+        out.write(content); out.flush(); os.fsync(out.fileno())
+    os.replace(tmp,dest)   # sustitución atómica, patrón v0.8.1
+except Exception:
+    try: os.unlink(tmp)
+    except OSError: pass
+    sys.exit(1)
+PY
+    then
+      applied=$((applied + 1))
+    fi
+  done
+fi
+
+if [ "$applied" -lt "$planned" ]; then
+  # Convergencia parcial: NO se sella el hash nuevo (el lock mentiría sobre lo que hay en
+  # disco). El próximo SessionStart reintenta solo lo que falta.
+  echo "⚠ contexto: $applied/$planned archivo(s) sincronizados; el lock sigue en '${CURRENT:-vacío}'. Se reintenta en la próxima sesión." >&2
+  exit 0
+fi
+
+FILES_JSON="$(python3 - "$WORK/manifest.json" <<'PY' 2>/dev/null
+import json,sys
+try:
+    man=json.load(open(sys.argv[1]))
+except Exception:
+    man={}
+out=[]
+for f in (man.get("files") or []):
+    if isinstance(f,dict) and f.get("path"):
+        out.append({"path":f.get("path"),"sha256":f.get("sha256"),
+                    "type_key":f.get("type_key"),"version":f.get("version")})
+print(json.dumps(out,ensure_ascii=False))
+PY
+)"
+[ -n "$FILES_JSON" ] || FILES_JSON='[]'
+runtime_lock_write "$NEWHASH" "$FILES_JSON"
+
+# Señal de sincronización: endpoint propio (es la única señal SIN slice_id del protocolo).
+# 422 = manifiesto desconocido para el servidor -> no se reintenta ni se encola.
+CHANGED_JSON="$(python3 - "$WORK/plan.tsv" <<'PY' 2>/dev/null
+import json,sys
+paths=[]
+try:
+    for line in open(sys.argv[1]):
+        line=line.rstrip("\n")
+        if line:
+            paths.append(line.split("\t")[0])
+except Exception:
+    pass
+print(json.dumps(paths,ensure_ascii=False))
+sys.stdout.flush()
+PY
+)"
+[ -n "$CHANGED_JSON" ] || CHANGED_JSON='[]'
+runtime_post "/context/synced" "{\"from_hash\":\"$CURRENT\",\"to_hash\":\"$NEWHASH\",\"files_changed\":$CHANGED_JSON}" >/dev/null
+ST="$(runtime_http_status)"
+[ "$ST" = "422" ] && echo "⚠ el runtime no reconoce el manifiesto sincronizado (422): revisa 'trycore-build doctor'." >&2
+
+if [ "$applied" -gt 0 ]; then
+  echo "⬆ contexto: $applied archivo(s) actualizados (${CURRENT:-sin lock} → $NEWHASH)"
+fi
+if [ -s "$WORK/skipped.txt" ]; then
+  echo "   No aplicados (destino no gobernado por este canal): $(tr '\n' ' ' < "$WORK/skipped.txt")"
+fi
+exit 0