@trycore/spec-build-harness 0.8.4 → 0.10.0

package/hooks/build/dual-compare.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# dual-compare.sh — comparador dual (hook Stop) [EP-OR-08-E].
+# En modo dual el fichero es primario y cada transición se espeja al runtime
+# (protocolo-cliente-runtime §10: POST …/mirror/transitions). Este comparador detecta
+# cuando el REDUCER del servidor llegó a una proyección distinta de lo que dice el
+# fichero local — señal de un espejo rechazado o perdido. Discrepancia = issue
+# bloqueante DEL CORTE (spec riesgos §4: "Divergencia dual… comparador automático en el
+# hook Stop; discrepancia = issue bloqueante del corte") — nunca bloquea el trabajo
+# local, se escala para revisión humana vía el mismo canal que /build:escalate.
+# Fail-open en TODO: sin dual, sin python3, sin build-state.json o con JSON corrupto,
+# sale 0 sin escalar nada.
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/lib/runtime-client.sh"
+source "$HERE/lib/agent-context.sh"
+
+MODE="$(runtime_mode)"
+[ "$MODE" = "dual" ] || exit 0
+command -v python3 >/dev/null 2>&1 || exit 0
+
+ROOT="$(config_root)"
+STATE_FILE="$ROOT/.claude/state/build-state.json"
+[ -f "$STATE_FILE" ] || exit 0
+
+# Refresco best-effort ANTES de comparar: Stop no es sensible a latencia como
+# PreToolUse (protocolo §4.2-B), y sin refresco fresco una discrepancia real podría
+# quedar enmascarada por una caché vieja de esta misma sesión.
+agent_context_fetch_and_cache >/dev/null 2>&1 || true
+
+FILE_SLICE="$(python3 - "$STATE_FILE" <<'PY' 2>/dev/null
+import json,sys
+try:
+    st = json.load(open(sys.argv[1]))
+except Exception:
+    print("null")
+    sys.exit(0)
+sl = st.get("active_slice")
+if not isinstance(sl, dict):
+    print("null")
+else:
+    print(json.dumps({
+        "epica": sl.get("epica"),
+        "phase": sl.get("phase"),
+        "gates": sl.get("gates") if isinstance(sl.get("gates"), dict) else {},
+    }))
+PY
+)"
+[ -n "$FILE_SLICE" ] || exit 0
+
+PROJ="$(runtime_projection_read)"
+
+REASONS_JSON="$(python3 - "$FILE_SLICE" "$PROJ" <<'PY' 2>/dev/null
+import json,sys
+try:
+    file_slice = json.loads(sys.argv[1])
+    proj = json.loads(sys.argv[2]) if sys.argv[2] else {}
+except Exception:
+    print("[]")
+    sys.exit(0)
+proj_slice = proj.get("active_slice") if isinstance(proj, dict) else None
+
+reasons = []
+if file_slice and not proj_slice:
+    reasons.append("el fichero tiene un slice activo (%s) pero el runtime no reporta ninguno" % file_slice.get("epica"))
+elif proj_slice and not file_slice:
+    reasons.append("el runtime reporta un slice activo (%s) pero el fichero no tiene ninguno" % proj_slice.get("epic_code"))
+elif file_slice and proj_slice:
+    if file_slice.get("epica") != proj_slice.get("epic_code"):
+        reasons.append("épica distinta: fichero=%s runtime=%s" % (file_slice.get("epica"), proj_slice.get("epic_code")))
+    if file_slice.get("phase") != proj_slice.get("phase"):
+        reasons.append("fase distinta: fichero=%s runtime=%s" % (file_slice.get("phase"), proj_slice.get("phase")))
+    fg = file_slice.get("gates") or {}
+    pg = proj_slice.get("gates") or {}
+    for k in sorted(set(fg) & set(pg)):
+        fv, pv = fg.get(k), pg.get(k)
+        # Solo gates YA resueltos en ambos lados (True/False); null=pendiente no cuenta.
+        if fv is not None and pv is not None and fv != pv:
+            reasons.append("gate %s distinto: fichero=%s runtime=%s" % (k, fv, pv))
+
+print(json.dumps(reasons, ensure_ascii=False))
+PY
+)"
+[ -n "$REASONS_JSON" ] && [ "$REASONS_JSON" != "[]" ] || exit 0
+
+REASON_TEXT="$(python3 -c "import json,sys; print('; '.join(json.loads(sys.argv[1])))" "$REASONS_JSON" 2>/dev/null)"
+[ -n "$REASON_TEXT" ] || exit 0
+
+echo "⚠ dual: discrepancia entre el fichero local y la proyección del runtime — ${REASON_TEXT}" >&2
+echo "   Se escala para revisión humana (el corte a modo runtime queda bloqueado mientras haya discrepancias sin resolver)." >&2
+
+"$HERE/slice-ops.sh" escalate "Discrepancia dual: ${REASON_TEXT}" >/dev/null 2>&1 || true
+exit 0

package/hooks/build/event-emitter.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# event-emitter.sh — PostToolUse (Bash|Edit|Write|MultiEdit|Task) [EP-OR-08-B].
+# La telemetría es propiedad del arnés, no del modelo: este hook NO puede omitirse desde
+# el prompt. Encola en .claude/state/outbox/ y devuelve el control de inmediato — el
+# despacho a POST /events lo hace el daemon (protocolo §2/§5). Nunca abre socket.
+# Contenido: SOLO metadatos (herramienta, ruta relativa, argv0). Jamás código fuente ni
+# el comando completo (protocolo §8: el arnés no envía fuente al runtime, y un comando
+# puede llevar credenciales).
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/lib/runtime-client.sh"
+source "$HERE/lib/projection.sh"
+
+MODE="$(runtime_mode)"
+[ "$MODE" = "legacy" ] && exit 0
+
+payload="$(cat 2>/dev/null || true)"
+command -v python3 >/dev/null 2>&1 || exit 0
+
+SLICE_ID="$(projection_get active_slice.slice_id "")"
+if [ -n "$SLICE_ID" ]; then
+  TMPP="$(mktemp)" || exit 0
+  printf '%s' "$payload" > "$TMPP"
+  EV="$(PROJECT_ROOT="$(config_root)" python3 - "$TMPP" <<'PY' 2>/dev/null
+import json,os,re,shlex,sys
+try:
+    p=json.load(open(sys.argv[1]))
+except Exception:
+    raise SystemExit(0)
+if not isinstance(p,dict):
+    raise SystemExit(0)
+tool=p.get("tool_name") or ""
+if not tool:
+    raise SystemExit(0)
+ti=p.get("tool_input")
+if not isinstance(ti,dict):
+    ti={}
+out={"tool":tool}
+if tool=="Bash":
+    cmd=str(ti.get("command") or "").strip()
+    # shlex.split (posix=True) respeta comillas: una asignación de entorno inline con
+    # valor citado y espacios (p.ej. `KEY="a b" cmd`) se tokeniza como UN solo token, no
+    # se trocea. Si el comando trae comillas sin cerrar u otro problema de tokenización,
+    # shlex lanza ValueError: no arriesgamos un fragmento de secreto, degradamos a "".
+    try:
+        toks=shlex.split(cmd) if cmd else []
+    except ValueError:
+        toks=[]
+    # Salta asignaciones de variable de entorno inline al frente (p.ej. `VAR=secreto cmd`,
+    # `A=1 B=2 cmd`) para que argv0 sea siempre el binario, nunca un valor que pueda
+    # llevar credenciales (protocolo §8).
+    i=0
+    while i < len(toks) and re.match(r'^[A-Za-z_][A-Za-z0-9_]*=', toks[i]):
+        i += 1
+    out["argv0"]=toks[i] if i < len(toks) else ""
+elif tool=="Task":
+    out["subagent_type"]=str(ti.get("subagent_type") or "")
+else:
+    fp=str(ti.get("file_path") or ti.get("path") or "")
+    root=os.environ.get("PROJECT_ROOT") or ""
+    if root and fp.startswith(root+os.sep):
+        fp=fp[len(root)+1:]
+    out["path"]=fp
+print(json.dumps(out,ensure_ascii=False))
+PY
+)"
+  rm -f "$TMPP"
+  [ -n "$EV" ] && runtime_enqueue_event "tool_use_recorded" "$EV" "$SLICE_ID"
+fi
+
+# Comprobación barata del daemon (stat del pidfile + kill -0, SIN red): un daemon caído a
+# mitad de sesión no debe quedar muerto durante horas hasta el próximo SessionStart.
+bash "$HERE/heartbeat.sh" --ensure "$PPID" >/dev/null 2>&1
+
+exit 0

package/hooks/build/gitflow-guard.sh

@@ -1,11 +1,31 @@
 #!/usr/bin/env bash
 # gitflow-guard.sh — PreToolUse · Bash
 # Enforce GitHub Flow estricto:
-#   - Prohíbe `git commit` directo en main/master.
-#   - Prohíbe `git push` que apunte a main/master (la integración va por PR).
-#   - Exige trabajar en rama feature/* | fix/* | chore/* para commitear.
-# Bloquea con exit 2 (stderr se devuelve a Claude). Cualquier otra cosa -> exit 0.
-set -euo pipefail
+#   - Prohíbe `git commit` directo en las ramas protegidas.
+#   - Prohíbe `git push` que apunte a una rama protegida (la integración va por PR).
+#   - Exige trabajar en una rama con prefijo declarado para commitear.
+# [EP-OR-08-B] Correcciones:
+#   1. La rama se resuelve en el repo del COMANDO (`git -C <dir>`, `cd <dir> && git …`),
+#      no en el de la sesión: en sesiones multi-repo el guard evaluaba el repo equivocado
+#      (spec §9). Sin pistas en el comando, se cae al repo de la sesión, como antes.
+#      El comando se tokeniza en segmentos (por &&, ||, ; y |) y se aplica el efecto
+#      ACUMULATIVO de los `cd`: si hay varios `cd` antes del segmento que ejecuta el git,
+#      gana el ÚLTIMO (el directorio real en el que corre el commit), no el primero.
+#   2. La política (prefijos y ramas protegidas) sale del asset sincronizado
+#      .claude/config/policy.json — el mismo que escribe context-sync.sh. Sin fichero,
+#      los defaults son los de v0.8.5: feature|fix|chore y main|master.
+#   3. Los prefijos/ramas de la política se escapan (re.escape) antes de entrar al patrón
+#      grep -E: son texto de un asset editable, no regex de confianza, y un metacaracter
+#      (p.ej. un punto) no debe interpretarse como comodín.
+#   4. `-C <dir>` solo cuenta como cambio de repo cuando es el flag GLOBAL de git (aparece
+#      antes del primer subcomando, p.ej. `git -C <dir> commit`). `git commit -C <ref>`
+#      es un flag del subcomando commit (reusa mensaje/autoría de otro commit) y NO cambia
+#      de directorio: tratarlo como tal dejaba el commit sin veredicto (bypass).
+# Cero red (PreToolUse). `set -uo pipefail` — nunca `-e`: este hook no puede abortar a
+# mitad y dejar pasar un commit sin veredicto.
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/lib/config.sh"
 
 INPUT="$(cat)"
 
@@ -39,27 +59,157 @@ if [ "$is_commit" = false ] && [ "$is_push" = false ]; then
   exit 0
 fi
 
-BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '')"
+# ── Repo del comando ──
+# Tokeniza el comando en segmentos (por &&, ||, ; y |) y camina en orden: cada `cd`
+# actualiza el directorio "vigente" (acumulativo — gana el ÚLTIMO visto); al llegar al
+# segmento que invoca el git de escritura, ese directorio vigente es el candidato, salvo
+# que el propio segmento traiga `-C <dir>` como flag GLOBAL de git (antes del subcomando),
+# que gana por ser más explícito y local a esa invocación.
+REPO_DIR="$(CMD="$CMD" python3 - <<'PY' 2>/dev/null
+import os,re,shlex
+
+cmd = os.environ.get("CMD", "")
+# Heurística de partición de shell (no un parser completo): &&, ||, ; y | en ese orden
+# de prioridad para que "||" no se rompa en dos "|".
+segments = re.split(r'&&|\|\||;|\|', cmd)
+
+
+def cd_target(seg):
+    m = re.match(r'^\s*cd\s+(.+?)\s*$', seg)
+    if not m:
+        return None
+    try:
+        toks = shlex.split(m.group(1).strip())
+    except Exception:
+        toks = [m.group(1).strip().strip("\"'")]
+    return toks[0] if toks else None
+
+
+ENV_ASSIGNMENT_RE = re.compile(r'^[A-Za-z_][A-Za-z0-9_]*=')
+# Envoltorios comunes que anteponen el nombre del binario real sin ser el subcomando de
+# git: `env FOO=x git ...`, `sudo git ...`. Solo se salta el nombre del envoltorio en sí
+# (no sus propias flags) — cubre el caso reportado sin pretender ser un parser de sudo/env.
+WRAPPER_CMDS = {"env", "sudo", "nice", "ionice", "time", "nohup"}
+# Flags GLOBALES de git que toman un argumento en un token SEPARADO: si no se saltan como
+# par, el walk trata el valor (p.ej. "user.name=x" de `-c user.name=x`) como si fuera el
+# subcomando y para ahí, sin llegar nunca al `-C` real que viene después (bypass).
+GIT_GLOBAL_FLAGS_WITH_ARG = {"-c", "-C", "--git-dir", "--work-tree", "--namespace", "--super-prefix"}
+
+
+def find_git_token(toks):
+    # Salta asignaciones de variables de entorno (`FOO=x git ...`) y envoltorios conocidos
+    # (`env`, `sudo`, ...) antes del `git` real — sin esto, `toks[0] != "git"` descarta el
+    # segmento entero y el -C real queda sin detectar (bypass: cae al repo de sesión).
+    i = 0
+    while i < len(toks) and (ENV_ASSIGNMENT_RE.match(toks[i]) or toks[i] in WRAPPER_CMDS):
+        i += 1
+    return i if i < len(toks) and toks[i] == "git" else None
+
+
+def git_global_dash_c(seg):
+    # `-C <dir>` solo cuenta si aparece ANTES del primer subcomando (commit/push/…): ahí
+    # es el flag GLOBAL de git. Tras el subcomando es un flag suyo (p.ej. `commit -C <ref>`
+    # reusa mensaje/autoría de otro commit) y no debe leerse como cambio de directorio.
+    try:
+        toks = shlex.split(seg)
+    except Exception:
+        return None
+    gi = find_git_token(toks)
+    if gi is None:
+        return None
+    i = gi + 1
+    while i < len(toks):
+        t = toks[i]
+        if t == "-C" and i + 1 < len(toks):
+            return toks[i + 1]
+        if t in GIT_GLOBAL_FLAGS_WITH_ARG and i + 1 < len(toks):
+            i += 2  # flag GLOBAL con argumento en token separado (p.ej. -c user.name=x):
+            continue  # se salta el PAR completo, nunca se lee el valor como subcomando.
+        if t.startswith("-"):
+            i += 1
+            continue
+        break  # primer token que no es flag => subcomando; -C posterior no cuenta.
+    return None
+
+
+cur_dir = ""
+target = ""
+for seg in segments:
+    seg = seg.strip()
+    if not seg:
+        continue
+    cdt = cd_target(seg)
+    if cdt is not None:
+        cur_dir = cdt
+        continue
+    if re.search(r'(^|\s)git(\s|$)', seg) and re.search(r'\b(commit|push)\b', seg):
+        dashc = git_global_dash_c(seg)
+        target = dashc if dashc else cur_dir
+        break
+
+print(target)
+PY
+)"
+if [ -n "$REPO_DIR" ]; then
+  case "$REPO_DIR" in
+    /*) ;;
+    *)  REPO_DIR="$(config_root)/$REPO_DIR" ;;
+  esac
+else
+  REPO_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+fi
+[ -d "$REPO_DIR" ] || REPO_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+BRANCH="$(git -C "$REPO_DIR" rev-parse --abbrev-ref HEAD 2>/dev/null || echo '')"
+
+# ── Política (asset sincronizado, defaults v0.8.5) ──
+POLICY="$(config_root)/.claude/config/policy.json"
+POLICY_OUT="$(POLICY="$POLICY" python3 - <<'PY' 2>/dev/null
+import json,os,re
+try:
+    d=json.load(open(os.environ["POLICY"]))
+except Exception:
+    d={}
+if not isinstance(d,dict):
+    d={}
+pref=[p for p in (d.get("branch_prefixes") or []) if isinstance(p,str)] or ["feature","fix","chore"]
+prot=[p for p in (d.get("protected_branches") or []) if isinstance(p,str)] or ["main","master"]
+# [EP-OR-08-B] re.escape: los prefijos/ramas vienen de un asset editable (policy.json), no son
+# regex de confianza. Sin escapar, un metacaracter (p.ej. un punto en "release.candidate")
+# se interpreta como comodín y afloja o rompe el gate silenciosamente.
+pref_re="|".join(re.escape(p) for p in pref)
+prot_re="|".join(re.escape(p) for p in prot)
+print("^(" + pref_re + ")/", "^(" + prot_re + ")$")
+PY
+)"
+case "$POLICY_OUT" in
+  *' '*) ;;
+  *) POLICY_OUT='^(feature|fix|chore)/ ^(main|master)$' ;;
+esac
+PREFIX_RE="${POLICY_OUT%% *}"
+PROT_RE="${POLICY_OUT##* }"
 
 block() {
   echo "⛔ gitflow-guard (GitHub Flow estricto): $1" >&2
-  echo "   Política: main protegida · trabajar en feature/* | fix/* | chore/* · integrar por PR." >&2
+  echo "   Política: ramas protegidas ${PROT_RE} · trabajar en ${PREFIX_RE}* · integrar por PR." >&2
+  echo "   Repo evaluado: $REPO_DIR (rama '$BRANCH')." >&2
   exit 2
 }
 
-# 1) Commit directo a main/master.
-if [ "$is_commit" = true ] && printf '%s' "$BRANCH" | grep -Eq '^(main|master)$'; then
+# 1) Commit directo a una rama protegida.
+if [ "$is_commit" = true ] && printf '%s' "$BRANCH" | grep -Eq "$PROT_RE"; then
   block "commit directo a '$BRANCH' no permitido. Crea una rama: git switch -c feature/<slug>"
 fi
 
 # 2) Commit desde una rama no tipada.
-if [ "$is_commit" = true ] && [ -n "$BRANCH" ] && ! printf '%s' "$BRANCH" | grep -Eq '^(feature|fix|chore)/'; then
-  block "rama '$BRANCH' no sigue la convención. Usa feature/* | fix/* | chore/* para commitear."
+if [ "$is_commit" = true ] && [ -n "$BRANCH" ] && ! printf '%s' "$BRANCH" | grep -Eq "$PREFIX_RE"; then
+  block "rama '$BRANCH' no sigue la convención. Usa un prefijo declarado en la política para commitear."
 fi
 
-# 3) Push apuntando a main/master.
-if [ "$is_push" = true ] && printf '%s' "$CMD" | grep -Eq 'push[^|;&]*[ :](main|master)([ ]|$|:)'; then
-  block "push directo a main/master no permitido. Abre un Pull Request desde tu rama feature/*."
+# 3) Push apuntando a una rama protegida.
+PROT_ALT="$(printf '%s' "$PROT_RE" | sed -e 's/^\^(//' -e 's/)\$$//')"
+if [ "$is_push" = true ] && printf '%s' "$CMD" | grep -Eq "push[^|;&]*[ :]($PROT_ALT)([ ]|$|:)"; then
+  block "push directo a una rama protegida no permitido. Abre un Pull Request desde tu rama de trabajo."
 fi
 
 exit 0

package/hooks/build/heartbeat.sh

@@ -0,0 +1,259 @@
+#!/usr/bin/env bash
+# heartbeat.sh — daemon singleton por repo [EP-OR-08-B, spec §4.3].
+#   uso: heartbeat.sh [--ensure <ppid>] | --daemon | --stop     (default: --ensure $PPID)
+#
+# Por qué un daemon y no un hook: no existe evento Timer, los hooks son efímeros y un
+# PostToolUse throttled NO late durante una tool call larga (suites de >5 min contra un
+# TTL de 300 s). Ciclo de vida explícito:
+#   - Singleton por repo: pidfile + fichero de sesiones interesadas en .claude/state/.
+#   - Cada SessionStart registra su ppid y RELANZA el daemon si el pidfile está muerto;
+#     cada PostToolUse hace la misma comprobación barata (stat + kill -0, SIN red).
+#   - Muere cuando no queda NINGÚN ppid registrado vivo (no cuando muere el primero):
+#     dos sesiones sobre el mismo repo comparten daemon.
+#   - Deberes por tick: consumir el sentinela de flush y despachar la cola; cada
+#     lease_ttl_s/3, renovar el lease. Sin lease NO se apaga (los eventos de ámbito
+#     proyecto, pre-claim, necesitan despachador).
+#   - Nunca se cuelga de Stop (dispara cada turno) ni de SessionEnd (no existe).
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/lib/runtime-client.sh"
+source "$HERE/lib/projection.sh"
+
+HB_TICK_S="${TRYCORE_HEARTBEAT_TICK_S:-5}"
+case "$HB_TICK_S" in ''|*[!0-9]*) HB_TICK_S=5 ;; 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"; }
+hb_flushfile() { echo "$(runtime_outbox_dir)/.flush-request"; }
+hb_spawnlock() { echo "$(config_root)/.claude/state/.heartbeat.spawn.lock"; }
+
+# hb_alive — rc 0 si hay un daemon vivo según el pidfile.
+hb_alive() {
+  local f pid
+  f="$(hb_pidfile)"
+  [ -f "$f" ] || return 1
+  pid="$(cat "$f" 2>/dev/null)"
+  case "$pid" in ''|*[!0-9]*) return 1 ;; esac
+  kill -0 "$pid" 2>/dev/null
+}
+
+# hb_register_session <ppid> — upsert idempotente del ppid en el registro de sesiones.
+hb_register_session() {
+  local ppid="${1:-}" f
+  case "$ppid" in ''|*[!0-9]*) return 0 ;; esac
+  f="$(hb_sessions)"
+  mkdir -p "$(dirname "$f")"
+  command -v python3 >/dev/null 2>&1 || return 0
+  python3 - "$f" "$ppid" <<'PY' 2>/dev/null
+import json,sys,os,tempfile
+path,ppid=sys.argv[1],int(sys.argv[2])
+try:
+    d=json.load(open(path))
+except Exception:
+    d={}
+if not isinstance(d,dict):
+    d={}
+ppids=[p for p in (d.get("ppids") or []) if isinstance(p,int)]
+if ppid not in ppids:
+    ppids.append(ppid)
+d["ppids"]=ppids
+dirn=os.path.dirname(path) or "."
+fd,tmp=tempfile.mkstemp(dir=dirn,prefix=".heartbeat-sessions.",suffix=".tmp")
+try:
+    with os.fdopen(fd,"w") as out:
+        json.dump(d,out,indent=2)
+    os.replace(tmp,path)
+except Exception:
+    try: os.unlink(tmp)
+    except OSError: pass
+PY
+  return 0
+}
+
+# hb_prune_sessions — deja en el registro solo los ppids vivos e imprime cuántos quedan.
+# La lista se materializa en un fichero temporal y se itera con `while read` (bash 3.2:
+# nada de mapfile) para poder aplicar `kill -0` a cada uno.
+hb_prune_sessions() {
+  local f tmp pid n
+  f="$(hb_sessions)"
+  [ -f "$f" ] || { echo 0; return 0; }
+  command -v python3 >/dev/null 2>&1 || { echo 0; return 0; }
+  tmp="$(mktemp)" || { echo 0; return 0; }
+  python3 - "$f" > "$tmp" <<'PY' 2>/dev/null
+import json,sys
+try:
+    d=json.load(open(sys.argv[1]))
+except Exception:
+    d={}
+for p in (d.get("ppids") or []):
+    print(p)
+PY
+  local live=()
+  while IFS= read -r pid; do
+    case "$pid" in ''|*[!0-9]*) continue ;; esac
+    kill -0 "$pid" 2>/dev/null && live+=("$pid")
+  done < "$tmp"
+  rm -f "$tmp"
+  n=${#live[@]}
+  if [ "$n" -gt 0 ]; then
+    python3 - "$f" "${live[@]}" <<'PY' 2>/dev/null
+import json,sys,os,tempfile
+path=sys.argv[1]
+ppids=[int(x) for x in sys.argv[2:]]
+dirn=os.path.dirname(path) or "."
+fd,tmp=tempfile.mkstemp(dir=dirn,prefix=".heartbeat-sessions.",suffix=".tmp")
+try:
+    with os.fdopen(fd,"w") as out:
+        json.dump({"ppids":ppids},out,indent=2)
+    os.replace(tmp,path)
+except Exception:
+    try: os.unlink(tmp)
+    except OSError: pass
+PY
+  fi
+  echo "$n"
+}
+
+# hb_write_status <json> — estado observable del daemon (lo lee statusline-bridge.sh).
+hb_write_status() {
+  local body f
+  body="$1"
+  f="$(hb_statusfile)"
+  mkdir -p "$(dirname "$f")"
+  command -v python3 >/dev/null 2>&1 || return 0
+  python3 - "$f" "$body" <<'PY' 2>/dev/null
+import json,sys,os,tempfile
+path,body=sys.argv[1],sys.argv[2]
+try:
+    d=json.loads(body)
+except Exception:
+    d={}
+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)
+    os.replace(tmp,path)
+except Exception:
+    try: os.unlink(tmp)
+    except OSError: pass
+PY
+  return 0
+}
+
+# hb_renew — renueva el lease del slice activo. El servidor responde SIEMPRE 409 de cuerpo
+# único cuando el lease ya no es nuestro (anti-oráculo HU-OR-41a): esa es la señal de
+# «lease perdido». No se apaga el daemon; se marca el estado y se sigue despachando.
+hb_renew() {
+  local slice_id agent_key resp status
+  slice_id="$(projection_get active_slice.slice_id "")"
+  [ -n "$slice_id" ] || return 0
+  agent_key="$(runtime_field agent_key)"
+  resp="$(runtime_put "/leases/renew" "{\"agent_key\":\"$agent_key\",\"slice_id\":\"$slice_id\"}")"
+  status="$(runtime_http_status)"
+  case "$status" in
+    200)
+      hb_write_status "{\"lease_lost\": false, \"slice_id\": \"$slice_id\", \"last_renew_status\": 200}"
+      return 0
+      ;;
+    409)
+      hb_write_status "{\"lease_lost\": true, \"slice_id\": \"$slice_id\", \"last_renew_status\": 409}"
+      return 1
+      ;;
+    *)
+      # Red caída: no se toca el estado anterior (no es lo mismo «sin red» que «lease perdido»).
+      return 1
+      ;;
+  esac
+}
+
+hb_daemon() {
+  local pidf interval ttl last now n
+  pidf="$(hb_pidfile)"
+  mkdir -p "$(dirname "$pidf")"
+  printf '%s' "$$" > "$pidf"
+  trap 'rm -f "$(hb_pidfile)"; exit 0' TERM INT EXIT
+  interval="${TRYCORE_HEARTBEAT_INTERVAL_S:-}"
+  case "$interval" in
+    ''|*[!0-9]*)
+      ttl="$(runtime_field lease_ttl_s)"
+      case "$ttl" in ''|*[!0-9]*) ttl=300 ;; esac
+      interval=$(( ttl / 3 ))
+      [ "$interval" -lt 10 ] && interval=10
+      ;;
+  esac
+  last=0
+  while :; do
+    sleep "$HB_TICK_S"
+    n="$(hb_prune_sessions)"
+    case "$n" in ''|*[!0-9]*) n=0 ;; esac
+    [ "$n" -eq 0 ] && break     # murió la última sesión interesada: el daemon se va con ella
+    if [ -f "$(hb_flushfile)" ]; then
+      rm -f "$(hb_flushfile)"
+      runtime_dispatch_outbox >/dev/null 2>&1
+    fi
+    now="$(date +%s)"
+    if [ $(( now - last )) -ge "$interval" ]; then
+      hb_renew
+      runtime_dispatch_outbox >/dev/null 2>&1
+      last="$now"
+    fi
+  done
+  rm -f "$pidf"
+  exit 0
+}
+
+# hb_spawn — lanza el daemon bajo un mutex de directorio (`mkdir` es atómico): dos
+# SessionStart simultáneos sobre el mismo repo no crean dos daemons. Un lock huérfano
+# (proceso muerto entre el mkdir y el rmdir) se libera por edad.
+#
+# El mutex cubre «daemon confirmado arriba», no solo «proceso bifurcado»: tras el nohup se
+# hace poll acotado (~3s) de hb_alive antes de soltar el lock. Sin esto, la ventana entre
+# el backgrounding y que el hijo escriba heartbeat.pid deja el lock libre con hb_alive aún
+# en falso; un --ensure casi simultáneo puede colarse ahí y lanzar un SEGUNDO daemon (se
+# autosana en el siguiente tick al ver 0 sesiones propias, pero produce renew/dispatch
+# duplicados transitorios mientras tanto).
+hb_spawn() {
+  local lock waited
+  lock="$(hb_spawnlock)"
+  mkdir -p "$(dirname "$lock")"
+  if [ -d "$lock" ] && [ -n "$(find "$lock" -maxdepth 0 -mmin +1 2>/dev/null)" ]; then
+    rmdir "$lock" 2>/dev/null
+  fi
+  mkdir "$lock" 2>/dev/null || return 0     # otro proceso está lanzando: nada que hacer
+  if ! hb_alive; then
+    nohup bash "$HERE/heartbeat.sh" --daemon >/dev/null 2>&1 &
+    waited=0
+    while [ "$waited" -lt 30 ]; do
+      hb_alive && break
+      sleep 0.1
+      waited=$((waited + 1))
+    done
+  fi
+  rmdir "$lock" 2>/dev/null
+  return 0
+}
+
+hb_ensure() {
+  [ "$(runtime_mode)" = "legacy" ] && return 0
+  hb_register_session "${1:-}"
+  hb_alive || hb_spawn
+  return 0
+}
+
+hb_stop() {
+  local pid
+  pid="$(cat "$(hb_pidfile)" 2>/dev/null)"
+  case "$pid" in ''|*[!0-9]*) ;; *) kill "$pid" 2>/dev/null ;; esac
+  rm -f "$(hb_pidfile)" "$(hb_sessions)"
+  return 0
+}
+
+case "${1:-}" in
+  --daemon) hb_daemon ;;
+  --stop)   hb_stop ;;
+  --ensure) hb_ensure "${2:-$PPID}" ;;
+  *)        hb_ensure "$PPID" ;;
+esac
+exit 0