merge: dev4 → master — rinomina capitano-bridge → heartbeat-bridge + role-map

# Conflicts:
#	.launcher/heartbeat-bridge.py

Author: leopu00

.launcher/agent-watchdog.sh

@@ -297,7 +297,7 @@ while true; do
     for role in "${AGENTS[@]}"; do
       ensure_agent "$role"
     done
-    # Bridge/daemon detached (sentinel/pacing/capitano-bridge/window-ratio/
+    # Bridge/daemon detached (sentinel/pacing/heartbeat-bridge/window-ratio/
     # codex-auth-healer + tg-bridge): respawn se morti, con anti-flap. Sono
     # fuori dal respawn-on-crash di pid1 (setsid), questo è il loro recovery.
     maybe_respawn_bridges

.launcher/capitano-bridge.py .launcher/heartbeat-bridge.py.launcher/capitano-bridge.py renamed to .launcher/heartbeat-bridge.py

@@ -1,6 +1,14 @@
 #!/usr/bin/env python3
 """
-capitano-bridge.py — heartbeat ORARIO al Capitano (2026-06-26).
+heartbeat-bridge.py — heartbeat ORARIO al Capitano (2026-06-26; ex capitano-bridge.py).
+
+── ROLE-MAP dei bridge deterministici (vedi docs/internal/architecture/bridges.md) ──
+  sentinel-bridge.py  → SENSORE usage: fetch provider ~2-10min (adattivo), scrive
+                        sentinel-data.jsonl, ticka la SENTINELLA ([BRIDGE TICK]).
+  pacing-bridge.py    → REPORT pacing: ogni 15min manda velocità/verdetto alla
+                        SENTINELLA ([BRIDGE PACING]). Il Capitano NON è pingato.
+  heartbeat-bridge.py → QUESTO: nudge orario al CAPITANO ([HEARTBEAT]); off-hours tace.
+  Due dei tre parlano alla SENTINELLA; solo questo parla al CAPITANO.
 
 Perché esiste: col push→pull (bridge→Sentinella) il Capitano non riceve più il
 [BRIDGE PACING] ogni 15 min, e si è osservato che resta INCAGLIATO quando la
@@ -21,13 +29,13 @@
 "segnale morbido" veniva razionalizzato via e la finestra chiusa a vuoto.
 
 Output:
-  - stdout (→ /tmp/capitano-bridge.log)
+  - stdout (→ /tmp/heartbeat-bridge.log)
   - tmux send al CAPITANO via jht-tmux-send (single-line)
 
 Modi:
-  python3 capitano-bridge.py            # loop orario allineato a :00
-  python3 capitano-bridge.py --once     # un colpo, stampa, niente send
-  python3 capitano-bridge.py --once --send
+  python3 heartbeat-bridge.py            # loop orario allineato a :00
+  python3 heartbeat-bridge.py --once     # un colpo, stampa, niente send
+  python3 heartbeat-bridge.py --once --send
 """
 import json
 import os
@@ -42,7 +50,7 @@
 SENTINEL_JSONL = LOGS_DIR / "sentinel-data.jsonl"
 AGENT_TABLE_FILE = LOGS_DIR / "agent-usage-table.json"
 DB_PATH = JHT_HOME / "jobs.db"
-STATE_FILE = LOGS_DIR / "capitano-bridge-state.json"
+STATE_FILE = LOGS_DIR / "heartbeat-bridge-state.json"
 # Daily hard-stop (#2): flag scritto dal sentinel-bridge a cap giornaliero sforato.
 # Lo leggiamo (sola lettura): a team in standby l'heartbeat orario tace.
 DAILY_HALT_FLAG = LOGS_DIR / "daily-halt.flag"
@@ -58,14 +66,14 @@
 # lecito (il re-wake resta del Capitano — vedi scout.md § idle).
 MESSAGES_JSONL = LOGS_DIR / "messages.jsonl"
 SCOUT_EXHAUST_LOOKBACK_H = float(
-    os.environ.get("JHT_CAPITANO_SCOUT_EXHAUST_LOOKBACK_H", "12")
+    os.environ.get("JHT_HEARTBEAT_SCOUT_EXHAUST_LOOKBACK_H", "12")
 )
-TARGET = os.environ.get("JHT_CAPITANO_HEARTBEAT_SESSION", "CAPITANO")
+TARGET = os.environ.get("JHT_HEARTBEAT_SESSION", "CAPITANO")
 DB_QUERY = "/app/shared/skills/db_query.py"
 
 
 def _log(msg):
-    print(f"[capitano-bridge] {msg}", file=sys.stdout, flush=True)
+    print(f"[heartbeat-bridge] {msg}", file=sys.stdout, flush=True)
 
 
 def _db_count(cmd):

.launcher/pacing-bridge.py

@@ -1,6 +1,13 @@
 #!/usr/bin/env python3
 """
-pacing-bridge.py — tick orario al Capitano sul ritmo di consumo del team.
+pacing-bridge.py — tick di pacing alla SENTINELLA sul ritmo di consumo del team.
+
+── ROLE-MAP dei bridge deterministici (vedi docs/internal/architecture/bridges.md) ──
+  sentinel-bridge.py  → SENSORE usage: fetch provider ~2-10min, scrive
+                        sentinel-data.jsonl, ticka la SENTINELLA ([BRIDGE TICK]).
+  pacing-bridge.py    → QUESTO: report pacing ogni 15min alla SENTINELLA
+                        ([BRIDGE PACING]). Il Capitano NON è pingato (pull on-demand).
+  heartbeat-bridge.py → nudge orario al CAPITANO ([HEARTBEAT]); off-hours tace.
 
 Ogni 15 minuti, allineato all'orologio (:00, :15, :30, :45 UTC), calcola:
 
@@ -34,7 +41,7 @@
 Modi:
   python3 pacing-bridge.py            # loop infinito allineato all'orologio
   python3 pacing-bridge.py --once     # un solo tick, stampa, niente send
-  python3 pacing-bridge.py --once --send  # un solo tick + send al CAPITANO
+  python3 pacing-bridge.py --once --send  # un solo tick + send alla SENTINELLA
 """
 import importlib.util
 import json

.launcher/sentinel-bridge.py

@@ -1,6 +1,12 @@
 #!/usr/bin/env python3
 """
-Sentinel Bridge V5 — orologio + fetch + tick alla Sentinella.
+Sentinel Bridge V5 — orologio + fetch + tick alla Sentinella (SENSORE usage).
+
+── ROLE-MAP dei bridge deterministici (vedi docs/internal/architecture/bridges.md) ──
+  sentinel-bridge.py  → QUESTO: SENSORE usage — fetch provider ~2-10min (adattivo),
+                        scrive sentinel-data.jsonl, ticka la SENTINELLA ([BRIDGE TICK]).
+  pacing-bridge.py    → report pacing ogni 15min alla SENTINELLA ([BRIDGE PACING]).
+  heartbeat-bridge.py → nudge orario al CAPITANO ([HEARTBEAT]); off-hours tace.
 
 Architettura V5 (post-incident 2026-04-25):
   • ogni 5 min: fetch del provider attivo (codex JSONL / kimi HTTP / claude HTTP)
@@ -78,7 +84,7 @@
 STATE_FILE = LOGS_DIR / "sentinel-bridge-state.json"
 # Daily hard-stop (#2): flag CONDIVISO. Quando il consumo di oggi sfora il cap
 # giornaliero, questo bridge lo crea e mette il team in standby; pacing-bridge e
-# capitano-bridge lo leggono e tacciono. Rimosso da questo stesso bridge quando il
+# heartbeat-bridge lo leggono e tacciono. Rimosso da questo stesso bridge quando il
 # budget rientra (inizio finestra di lavoro del giorno dopo / reset weekly).
 DAILY_HALT_FLAG = LOGS_DIR / "daily-halt.flag"
 STATE_VERSION = 7

.launcher/start-agent.sh

@@ -184,21 +184,21 @@ if [ "$ROLE" = "bridge" ]; then
   # push→pull il Capitano non riceve più il pacing ogni 15min e si incaglia
   # quando la Sentinella tace: questo lo risveglia 1×/ora con un nudge basato sui
   # dati DB (deterministico, NON LLM), così resta attivo senza essere passivo.
-  HEARTBEAT_SCRIPT="/app/.launcher/capitano-bridge.py"
+  HEARTBEAT_SCRIPT="/app/.launcher/heartbeat-bridge.py"
   if [ -f "$HEARTBEAT_SCRIPT" ]; then
-    for _pid in $(grep -l capitano-bridge.py /proc/[0-9]*/cmdline 2>/dev/null | sed 's|/proc/||;s|/cmdline||'); do
+    for _pid in $(grep -l heartbeat-bridge.py /proc/[0-9]*/cmdline 2>/dev/null | sed 's|/proc/||;s|/cmdline||'); do
       kill -TERM "$_pid" 2>/dev/null || true
     done
     sleep 0.5
-    for _pid in $(grep -l capitano-bridge.py /proc/[0-9]*/cmdline 2>/dev/null | sed 's|/proc/||;s|/cmdline||'); do
+    for _pid in $(grep -l heartbeat-bridge.py /proc/[0-9]*/cmdline 2>/dev/null | sed 's|/proc/||;s|/cmdline||'); do
       kill -KILL "$_pid" 2>/dev/null || true
     done
     sleep 0.5
     setsid sh -c "
-      JHT_CAPITANO_HEARTBEAT_SESSION='${JHT_TARGET_SESSION:-CAPITANO}' \
-        python3 -u $HEARTBEAT_SCRIPT >> /tmp/capitano-bridge.log 2>&1
+      JHT_HEARTBEAT_SESSION='${JHT_TARGET_SESSION:-CAPITANO}' \
+        python3 -u $HEARTBEAT_SCRIPT >> /tmp/heartbeat-bridge.log 2>&1
     " >/dev/null 2>&1 < /dev/null &
-    echo "✓ capitano-bridge (heartbeat orario) partito (log /tmp/capitano-bridge.log)"
+    echo "✓ heartbeat-bridge (nudge orario al Capitano) partito (log /tmp/heartbeat-bridge.log)"
   else
     echo "⚠ $HEARTBEAT_SCRIPT non trovato — heartbeat NON partito"
   fi

agents/_skills/maintainer-sweep/SKILL.md

@@ -16,7 +16,7 @@ Il Mantenitore **ripara** l'infra (installa deps mancanti, consolida, sistema).
 ## Lo sweep (7 step, in ordine)
 
 ### 0. 🫀 Liveness canary dei processi salva-vita (la rete di sicurezza)
-**PRIMO step, prima di tutto.** I bridge/daemon che fanno vivere il container (sentinel-bridge, pacing-bridge, capitano-bridge, window-ratio-meter, codex-auth-healer + tg-bridge) sono lanciati `setsid` detached → **fuori dal respawn-on-crash di pid1**. L'`agent-watchdog` (`maybe_respawn_bridges`) li risorveglia ogni 30s, MA se anche quello fallisse (bug, flap-cap raggiunto, watchdog stesso degradato) tu sei **l'ultima rete**: al primo sweep del giorno rilevi e ripari. Senza questo canary, un daemon morto resta invisibile per ore (è esattamente com'è successo al sentinel-bridge su andris il 2026-06-27 → 8h ciechi sull'usage).
+**PRIMO step, prima di tutto.** I bridge/daemon che fanno vivere il container (sentinel-bridge, pacing-bridge, heartbeat-bridge, window-ratio-meter, codex-auth-healer + tg-bridge) sono lanciati `setsid` detached → **fuori dal respawn-on-crash di pid1**. L'`agent-watchdog` (`maybe_respawn_bridges`) li risorveglia ogni 30s, MA se anche quello fallisse (bug, flap-cap raggiunto, watchdog stesso degradato) tu sei **l'ultima rete**: al primo sweep del giorno rilevi e ripari. Senza questo canary, un daemon morto resta invisibile per ore (è esattamente com'è successo al sentinel-bridge su andris il 2026-06-27 → 8h ciechi sull'usage).
 ```bash
 python3 /app/shared/skills/process_health.py summary
 ```

agents/capitano/capitano.de.md

@@ -76,7 +76,7 @@ Dein Operations-Loop. Erkenne den Trigger, öffne die Skill, führe aus.
 | **Beginn des Arbeitszeitfensters** (Tagesbeginn, erster `work_phase=ON`-Tick) — email-first Sourcing + Intake-Balancing | `email_monitor.py count`/`poll` → **C-16** |
 | Nachricht `[@utente -> @capitano] [CHAT]` | `chat-web` |
 | Nachricht `[SENTINELLA]` mit einem Rat | `sentinel-orders` (du interpretierst + verifizierst + entscheidest, C-01) |
-| Nachricht `[HEARTBEAT]` (stündlich, vom capitano-bridge) — **dein Puls**: neu bewerten | siehe **C-20** |
+| Nachricht `[HEARTBEAT]` (stündlich, vom heartbeat-bridge) — **dein Puls**: neu bewerten | siehe **C-20** |
 | **Das Pacing** on-demand prüfen (Zweifel an einem Sentinella-Rat, oder wer gerade verbrennt) — der Bridge pingt es dir nicht mehr, du **ziehst es selbst** (zero-cost) | `rate-budget` / `agent-speed-table` |
 | Du musst einen Agent spawnen | `spawn-agent` |
 | Leere Pipeline / Scaling-Entscheidung / Cold Start | `pipeline-triage` |
@@ -209,7 +209,7 @@ Ohne das gate-weighted C-09 kann die Autonomie C-07 in Phase 1 mit dem alten Mod
 - **🌅 Abendreserve (2026-06-26):** die `daily:`-Zeile trägt auch `riserva=R%→tieni|brucia`. **Tagsüber (`tieni`):** pace Richtung `budget − riserva`, fülle morgens **NICHT** bis zum Cap — lass R% für den Abend. **Letzte ~2h (`brucia`):** die Reserve wird frei → entweder nutzt der User sie, um **mit dem Team zu chatten**, oder du **verbrennst sie auf der Arbeit** (erhöhst das Tempo via C-02), damit kein Budget verschwendet wird und du beim Reset bei ~100% landest. Es ist der **Anti-Front-Load**: Kimi neigt dazu, am Vormittag fertig zu werden, und so kann der User am Abend noch mit dem Team interagieren.
 - Es ist kein Freeze und kein HALT (es gilt C-09: kein vorzeitiger HALT): es ist ein **Tages-Coast**. Beim Fensterwechsel (nächster Tag) startet der heutige Verbrauch wieder bei 0 und das Team nimmt mit der neu berechneten Quote wieder auf.
 
-**C-20 — `[HEARTBEAT]` = dein stündlicher Puls (2026-06-26).** Mit push→pull erhältst du das Pacing nicht mehr alle 15 min, und das Risiko ist, **passiv** zu bleiben, wenn die Sentinella schweigt. Deshalb sendet dir der `capitano-bridge` 1×/Stunde einen `[HEARTBEAT]`: es ist ein **deterministisches Werkzeug IN DEINEM DIENST** (kein Befehl, nicht die Sentinella), das dir auf Basis der **DB-Daten** eine **Frage/Bedingung** stellt, um dich zur **Neubewertung** zu bringen (Queues leer? verbrennt ein Worker ins Leere? bist du on-pace?). Bei seinem Eingang: **führe ihn nicht blind aus** — er ist ein Anstoß. **Verifiziere** mit deinen Skills (`pipeline-triage`, `rate-budget`, `agent-speed-table`, `capture-pane`), ob die Bedingung real ist, dann **entscheide und handle** du (spawn/kill/throttle/nichts). **Niemals einen Subagenten spawnen** für diese Prüfung (so beobachtet: ein `Task`, der einen Sub-Agenten öffnet, um die Pipeline abzufragen = eine volle Runde, zudem NICHT im Verbrauch erfasst) — die Skill `pipeline-triage` ist bereits ein **Skript**: führe sie direkt aus, eine knappe Query. Der Puls ist jetzt ein reines **Signal** (kein „entscheide du" mehr in der Nachricht): lies das Datum und handle **nur**, wenn es eine echte Anomalie bestätigt, mit EINER Skill. Es ist das Gegenteil des Festfahrens: es hält dich **aktiv** in der Koordination, ohne dich von der Sentinella abhängig zu machen. NB: manchmal **schweigt** der Heartbeat (alles in Ordnung) — das ist völlig in Ordnung, du machst deine Runde weiter.
+**C-20 — `[HEARTBEAT]` = dein stündlicher Puls (2026-06-26).** Mit push→pull erhältst du das Pacing nicht mehr alle 15 min, und das Risiko ist, **passiv** zu bleiben, wenn die Sentinella schweigt. Deshalb sendet dir der `heartbeat-bridge` 1×/Stunde einen `[HEARTBEAT]`: es ist ein **deterministisches Werkzeug IN DEINEM DIENST** (kein Befehl, nicht die Sentinella), das dir auf Basis der **DB-Daten** eine **Frage/Bedingung** stellt, um dich zur **Neubewertung** zu bringen (Queues leer? verbrennt ein Worker ins Leere? bist du on-pace?). Bei seinem Eingang: **führe ihn nicht blind aus** — er ist ein Anstoß. **Verifiziere** mit deinen Skills (`pipeline-triage`, `rate-budget`, `agent-speed-table`, `capture-pane`), ob die Bedingung real ist, dann **entscheide und handle** du (spawn/kill/throttle/nichts). **Niemals einen Subagenten spawnen** für diese Prüfung (so beobachtet: ein `Task`, der einen Sub-Agenten öffnet, um die Pipeline abzufragen = eine volle Runde, zudem NICHT im Verbrauch erfasst) — die Skill `pipeline-triage` ist bereits ein **Skript**: führe sie direkt aus, eine knappe Query. Der Puls ist jetzt ein reines **Signal** (kein „entscheide du" mehr in der Nachricht): lies das Datum und handle **nur**, wenn es eine echte Anomalie bestätigt, mit EINER Skill. Es ist das Gegenteil des Festfahrens: es hält dich **aktiv** in der Koordination, ohne dich von der Sentinella abhängig zu machen. NB: manchmal **schweigt** der Heartbeat (alles in Ordnung) — das ist völlig in Ordnung, du machst deine Runde weiter.
 
 **C-21 — Scouts im TEAM, nie allein auf gesättigtem Markt (2026-06-30).** Wenn du Scouts zum Sourcing spawnst, behandle sie als **koordiniertes Team**, nicht als parallele Einzelgänger. Den ERSTEN Scout auf leerer Queue spawnst du sofort (C-05, anti-idle), aber **sobald du über 1 skalierst, ist es ein Team**: jeder weitere Scout bekommt ein **geteiltes Territorium** (Circles/Sources/Städte/Ranges via Skill `scout-coord`), die Scouts **sprechen miteinander**, um neu aufzuteilen, wenn eine Quelle erschöpft ist, und ihr **Verbrauch muss AUSGEGLICHEN** sein — ein Scout bei 150 kT während ein anderer bei 16 kT ist, heißt sie teilen **NICHT** (sie kratzen dieselbe Quelle parallel): Territorien neu aufteilen oder den Runaway killen (C-12). Der schlimmste Fall ist ein **einzelner Scout, der einen gesättigten Markt abgrast** (wenige neue Stellen, sehr hohe Kosten/Fund — bei BARTO passiert): lass ihn nicht allein kratzen, **stell ihm einen zweiten zur Seite, der das Territorium aufteilt** — zu zweit decken sie mehr Markt zu geringeren Kosten ab, statt einer, der dieselben erschöpften Quellen wiederholt. Das Team schlägt den Einzelgänger: mehr Abdeckung, weniger Duplikate, faire Last.