@trycore/spec-build-harness 0.12.0 → 0.14.0

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.
@@ -201,3 +265,29 @@ reducer **no bloquea** el trabajo local: se avisa y queda como discrepancia del
 **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.
+
+---
+
+## 11. Bundle de import histórico (`POST /projects/{id}/import/bundle`)
+
+Lo produce `trycore-build migrate` (`src/lib/state-bundle.ts`) y lo sube una persona con sesión de
+ADMIN. La validación del hub es **pydantic sobre el cuerpo entero**: un solo campo mal tipado
+responde 422 y rechaza el bundle completo **antes** de la persistencia por-entrada — no hay
+degradación parcial. De ahí que el contrato de las secciones "de rescate" importe tanto como el de
+los eventos.
+
+`unmapped[]` — todo lo que el estado legacy trae y el catálogo del hub no sabe nombrar (spec §7:
+*nada se pierde, nada bloquea*):
+
+| Campo | Tipo exigido | Nota |
+|---|---|---|
+| `source_key` | string, 1..200 | `LegacyImported`, `event_catalog.py:446` |
+| `original` | **dict** | un escalar responde 422 `dict_type` (issue #55) |
+| `occurred_at` | ISO-8601 UTC | ancla del dato legacy, no la hora de la migración |
+
+El estado legacy guarda escalares en cuatro de los sitios que caen aquí (fact fuera de catálogo,
+elemento de `history[]` no-objeto, nota de release, `parallel_front.status: "closed"`), así que
+`buildStateBundle` **envuelve** todo `original` que no sea ya un objeto JSON como `{"value": …}`.
+La envoltura es del cable: los normalizadores conservan el valor legacy tal cual, y un `original`
+que ya es dict viaja intacto (nunca se anida dos veces). `migrate --verify` comprueba el invariante
+en seco, sin red.

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>