# PROTOCOLLO — servizio-gmail-check

Stesso principio "orologio vs giudizio" di `servizio-inbox-watch`/`servizio-gate-watch`: questo
servizio non è mai una LLM, non decide mai cosa è importante — controlla solo se è arrivata posta
nuova e lo segnala meccanicamente.

## Cosa fa

Ogni 20 minuti:
1. Legge `last_check.txt` (timestamp ISO dell'ultimo controllo riuscito).
2. Chiama `gmail_check.py (stessa cartella) --since <timestamp>` (via il venv locale se
   presente).
3. Se trova messaggi nuovi (`exit 0`, output JSON non vuoto): scrive intestazioni (mittente,
   oggetto, data — mai il corpo) direttamente in `mailbox.log` con sorgente `gmail-check`, e
   aggiorna `last_check.txt`.
4. Se non trova nulla (`exit 0`, output vuoto): aggiorna comunque `last_check.txt`, nessuna
   scrittura in mailbox — silenzio è il comportamento atteso.
5. Se `gmail_check.py` fallisce (`exit` diverso da 0, o timeout): **non** aggiorna
   `last_check.txt` (riprova dallo stesso punto al tick successivo), logga sempre in `watch.log`,
   ma scrive in mailbox al massimo una volta all'ora per non fare rumore su un guasto persistente
   (es. refresh token scaduto, rete assente).

## Chi giudica l'importanza

Nessuno a questo livello. Il demone di trigger di `gemello-nave` (`gemello-nave/trigger/watch.py`)
inoltra questi eventi a `gemello-nave` a freddo, che applica i criteri in `gemello-nave/archivio/
criteri-gmail.md` e segnala in mailbox (sender `gemello-nave`) se degno di attenzione — non un
Claude dedicato per ogni tick. **Handoff completo dall'11/09** (decisione esplicita di Mauro,
senza il periodo di osservazione prolungata usato per altri perimetri di `gemello-nave`): Adrian
non applica più questi criteri, non legge nemmeno le righe grezze `gmail-check:` (filtrate a monte
dalla sua checklist di avvio sessione) — se `gemello-nave` non segnala, quell'email non arriva a
nessuno. Se nessuna sessione Adrian è viva quando `gemello-nave` scrive una segnalazione, la voce
resta in mailbox fino al prossimo avvio sessione (stesso comportamento già accettato per tutte le
sentinelle/esperti/servizi, 31/08/2026).

**Nota storica (11/09)**: questo file rimandava ai criteri in
`scripts/slave-sentinels/sentinella-gmail-personale/CLAUDE.md` — cartella cancellata il 09/09 nello
smantellamento della sentinella, riferimento morto non corretto all'epoca. Recuperati dalla storia
git (commit `596c5a8~1`) e migrati in `gemello-nave/archivio/criteri-gmail.md` l'11/09, prima che
andassero persi per sempre.

## File

- `watch.py` — loop principale, systemd `Type=simple`, `Restart=on-failure`.
- `last_check.txt` — stato persistente, singola riga ISO8601.
- `watch.log` — log locale di ogni tick (trovato/non trovato/errore).
- `servizio-gmail-check.service` — unit systemd, installata in `/etc/systemd/system/` (richiede
  `sudo`, approvazione esplicita per modifiche systemd).

## Gestione

```
sudo systemctl status servizio-gmail-check
sudo systemctl restart servizio-gmail-check
journalctl -u servizio-gmail-check -f
tail -f gemello-nave/gmail-check/watch.log
```

## Dipendenze

- `.env (stessa cartella)` (credenziali OAuth, mai committato) deve esistere e essere valido —
  vedi `PROTOCOLLO.md (questo file)` per il setup.
- App OAuth `gmail-check-desktop` in stato "In produzione" (09/09/2026) — il refresh token non
  scade più a 7 giorni come accadeva in "Testing".