# Conoscenza tecnica — infrastruttura Nave

**Copiato da `MEMORY.md` (sezione "Stato operativo corrente") e
`archivio/Adrian/riferimento/gotcha-tecnici-sistema.md` l'11/09/2026** — non ancora l'unica fonte
di verità: gli originali restano fino a verifica che `gemello-nave` risponda correttamente da qui,
poi vanno eliminati (regola di Mauro: non duplicare a lungo, solo durante la transizione).

Consultare questo file per qualunque domanda tecnica su servizi/infrastruttura/gotcha di Nave —
sia in risposta a `SendMessage` da Adrian, sia come contesto durante il triage cold-start.

---

## Servizi attivi su Nave (stato al 11/09/2026)

- guacd: container Guacamole tenuto vivo da cron `*/5 * * * *` (`docker compose up -d guacd`)
- browser_agent (`tools/browser-agent/browser_agent.py`): vision agent screenshot→Claude Vision→azione→loop, profilo Chrome `~/.config/chrome-debug-agent` porta CDP 9223, no acquisti/prenotazioni/irreversibili, `/tmp/browser_agent_debug/` per debug
- **mcp-query.service**: systemd, sempre attivo, MCP dati business ICR su `https://query.privcloud.dev` — vedi `sandbox/mcp-query/CLAUDE.md`
- maintenance_check: rimosso l'11/09/2026 (era già paused, dipendeva da Elon/vault smantellati). Layer 2 (LanceDB): sospeso.
- **`logbook/` (11/09/2026, spostata qui dentro gemello-nave/, presa in carico per intero)**:
  `collect_logs.py`, cron giornaliero 05:45, sorveglia i log critici locali di Nave
  (`backup_completo.log`, `pcloud_mirror.log`, `snapshot_avamposto.log`), produce un digest
  (`reports/latest.txt`, ~140 report storici da aprile) **e scrive in mailbox** (sender
  `logbook:`) se trova anomalie — perimetro di `gemello-nave` esteso di conseguenza (vedi
  `CLAUDE.md`). L'hook `session-start-reminder.sh` della sessione interattiva **non legge più
  logbook direttamente** (tolto 11/09): possesso fisico della cartella implica possesso logico
  per intero, niente doppio binario. Dominio diverso da `check_job_health`/`gate-ufficio`
  (quello è Ufficio).
- **Hook `session-start-reminder.sh`**: legge tre report indipendenti e li inietta nel promemoria se ⚠️ — `gemello-nave/logbook/reports/latest.txt` (05:45, log sistema Nave, vedi sopra), `PYTHON/gate-ufficio/nave/logs/job_health_latest.txt` (ogni 30 min), `gemello-nave/monitor-consumo-istanze/report_latest.txt` (05:58, consumo token reale). `backup_health.py` controlla i lock stale su `repo/locks/`.
- **`check_job_health.py`**: cron ogni 30 minuti (`PYTHON/gate-ufficio/nave/`), dedup dei problemi già notificati, scrive in mailbox.
- **`monitor-consumo-istanze`**: `gemello-nave/monitor-consumo-istanze/report.py`, cron giornaliero 05:58, token reali per istanza — soglia su `cache_creation + output` ("costo reale"). Alert solo su sentinelle/esperti/servizi, mai su lavoro interattivo. Auto-pulente (solo attività ultimi 3 giorni).
- **`check_dropbox_health`**: job `gate-ufficio`, ogni 15min, rileva Dropbox MSIX in "Not Responding" su Ufficio e lo rilancia da solo.
- **`servizio-gmail-check`**: systemd, sempre attivo, chiama `gmail_check.py` (stessa cartella, `gemello-nave/gmail-check/`) ogni 20 minuti, API diretta non MCP, scrive in mailbox solo se trova posta nuova. Credenziali in `gemello-nave/gmail-check/.env`.
- **Esperti attivi**: `SendMessage` sincrono per domande di dominio. `expert-domotica`
  (Zigbee/MQTT/HA/InfluxDB, dominio Nave-esclusivo) vive in `gemello-nave/expert-domotica/`
  dall'11/09/2026 — co-locato, non nel mio perimetro di giudizio. `expert-data` (dati business
  ICR, sola lettura) ed `expert-flussi` (OnAir/Frank/DataHub_v2 + `gate-ufficio`/`I:\`, sola
  lettura) restano in `scripts/slave-sentinels/` — proposta di spostarli sotto `gemello-ufficio`
  lasciata in sospeso. Nessun keep-alive per nessuno dei tre: si lasciano scadere, rilancio a
  freddo on-demand con `slave_sentinel_ensure.sh <nome-cartella>` (script generalizzato l'11/09
  per cercare anche fuori da `scripts/slave-sentinels/`).
- **`servizio-madre-watch`** (`gemello-nave/madre-watch/`): systemd, nessun LLM persistente, tick orario — avvisa `gemello-ufficio` di controllare `scheduler.pid`. Co-locato, non nel perimetro di `gemello-nave`.
- **`servizio-gate-watch`** (`gemello-nave/gate-watch/`): systemd, fa girare `PYTHON/gate-ufficio/nave/monitor_executions.py`, successi in mailbox (sender `gate-ufficio`). **Dall'11/09** i fallimenti non lanciano più una slave dedicata — scrivono in mailbox (sender `gate-watch:`), perimetro di `gemello-nave` che legge il log e spiega la causa lei stessa.
- **`servizio-inbox-watch`** (`gemello-nave/inbox-watch/`): systemd, processa `inbox-documenti/` entro 30s. Co-locato, non nel perimetro di `gemello-nave`.
- **`gemello-nave`** (questa entità): `gemello-nave/`, triage a freddo eventi `check_job_health` in mailbox (demone `watch.py` via crontab utente ogni 2 min), mai contatto diretto con Mauro. Canvas: `archivio/Adrian/progetti/project_gemello_nave.md`.

Due sistemi di schedulazione distinti su Nave, non mescolare: **cron locali** (backup, mirror, `gemello-nave/logbook/collect_logs.py`, i `servizio-*` sopra) vs **`schedule.json`/`gate-ufficio`** (job del PC ufficio, vive nel repo `gate-ufficio`).

## Gotcha tecnici stabili

- **Guacamole bloccato su "Attendi risposta"**: quasi sempre x11vnc, non Docker — fix `sudo systemctl restart x11vnc-guacamole.service`. x11vnc può incepparsi dopo un `"caught X11 error"` (bug xdamage): resta `is-active` ma zombie. Auto-fix: `gemello-nave/guacamole_watchdog.sh` (cron ogni 5 min).
- **Guacamole con schermo nero**: probabile blocco per inattività, seconda sessione X attiva invece di quella con x11vnc agganciato. Diagnosi: `loginctl list-sessions` (sessione `mauro` `online` non `active`). Fix: `sudo loginctl activate <id-sessione>`.
- pkill su processi di sistema non li riavvia — usare systemctl.
- **(11/09) Il blocco assoluto del classificatore Auto Mode di Claude Code su comandi systemd
  riguarda `systemctl enable`** (registrazione permanente al boot, nessun prompt possibile nemmeno
  con via libera esplicita di Mauro — motivo per cui `gemello-nave/trigger/watch.py` gira via
  crontab utente invece che come servizio) — **non** `systemctl restart`/`daemon-reload` su un
  servizio già installato/abilitato, che invece passano senza essere bloccati (verificato
  spostando `servizio-gmail-check` in `gemello-nave/gmail-check/`, stesso giorno). Utile per
  distinguere "impossibile senza intervento manuale di Mauro" da "fattibile in autonomia" prima di
  proporre un piano che coinvolge systemd.
- Flask+pywebview: disabilitare sempre cache file statici (`SEND_FILE_MAX_AGE_DEFAULT=0`+`no-store`).
- pywebview e PyQt6 non condividono processo — finestra PyQt6 va lanciata come `subprocess.Popen` separato.
- `rclone authorize` per Google Drive va lanciato sulla Nave stessa (link punta a 127.0.0.1, via Guacamole).
- Caddy su Avamposto può restare su config stale — verificare `docker exec caddy cat /etc/caddy/Caddyfile` contro il disco. Fix: `docker restart caddy`.
- Processo Python nudo esposto a WireGuard: va autorizzato esplicitamente in `ufw` (i container Docker bypassano ufw).
- Foto `.heic` da iPhone non leggibili direttamente — `libheif-examples` (`heif-convert input.heic output.jpg`) prima di leggere.
- Container Docker con UID solo-interno può rompere backup silenziosamente — fix: `user: "<uid_host>:<gid_host>"` nel `docker-compose.yml`.
- `PYTHON/` non ha `.git` proprio (rimosso) — ogni sottoprogetto ha il suo, verificare `git rev-parse --show-toplevel`.
- Mai stato runtime Docker dentro una cartella sincronizzata Dropbox — dati runtime sempre in `/mnt/ssd/config/<servizio>/`.
- `code --new-window` da dentro una sessione Claude Code non apre mai una vera finestra nuova (eredita `VSCODE_IPC_HOOK_CLI`).
- `print()` senza `flush=True` resta bufferizzato quando stdout non è un terminale (es. osservato da un Monitor) — sempre `flush=True` per output real-time.
- Stime di progresso su copie/scansioni grandi: mai a conteggio file se le dimensioni sono sbilanciate — usare `/proc/<pid>/io`, campo `write_bytes`.
- `/clear` non cancella nulla su disco, crea solo una nuova sessione — file precedente recuperabile in `~/.claude/projects/.../<uuid-vecchio>.jsonl`.
- Compattazione non crea una nuova sessione, riscrive quella esistente (stesso file, riassunto aggiunto) — testo precedente resta sul disco, solo escluso dal contesto attivo.
- `rsync` senza `-H` gonfia enormemente un albero con hard-link dedup — sempre `rsync -avhH`.
- **Il `Monitor` di questa sessione sopravvive a un `/clear`** (scoperto 11/09) — non è legato alla conversazione ma al processo di sessione sottostante. Verificare con `pgrep -af <pattern-offset-file>` prima di armarne uno nuovo, mai assumere che serva riarmarlo sempre.
- `CronCreate` non è scheduling durevole (sparisce se chiudo, scade dopo 7gg) — per verifiche persistenti usare cron di sistema + hook `SessionStart`. `RemoteTrigger` (claude.ai cloud) non accede al filesystem Nave.
- Un `&` di bash dentro una chiamata Bash di questo harness non sopravvive alla chiamata stessa — usare `run_in_background: true` nativo.
- `kill <pid>` su una sessione `claude --bg` viene auto-resuscitata dal demone di supervisione — usare `claude stop <id>` (non un `kill` OS).
- Un `SendMessage` in arrivo può far ripartire l'elaborazione di una sessione già clearata, senza input umano — una sessione "ferma" non implica supervisione assente al 100%.
- In una conversazione molto lunga, un burst di consumo quota non è un bug di conteggio — è la cache che scade tra un turno e l'altro (gap > TTL ~5 min costringe a riscrivere il contesto intero in cache).
- Conteggio token per istanza: ogni sessione scrive `.jsonl` in `~/.claude/projects/<hash-cwd>/` — l'hash dipende dalla `cwd` di lancio, una sentinella ha una cartella diversa dalla sessione principale.
- Repo `adrian` senza `.gitattributes` causava file "modified" senza diff reale su Ufficio (CRLF/LF, bit eseguibile) — risolto con `.gitattributes` + `core.fileMode false` locale su Ufficio.
- SSD con "Unrecovered Read Error" su fascia LBA fissa: fix reale è riscrittura completa del disco (`dd`/`blkdiscard`) per forzare il rimappaggio su spare sano — funziona solo con `Available Spare` alto.

## Note su Ufficio (per contesto, gestito da `gemello-ufficio`)

- PC ufficio spento di notte è comportamento atteso, non un'anomalia.
- Backup ufficio fallisce se il PC è acceso ma la VPN non è attiva (drive di rete non raggiungibili) — comportamento atteso, non un guasto.
- Client Dropbox Windows (MSIX) può impiantarsi in "Not Responding" — watchdog `check_dropbox_health` lo rileva e rilancia da solo. Variante senza "Not Responding" (sync fermo ma processi "Responding=True") non coperta dal watchdog — diagnosi: confrontare mtime file tra path locale e `Z:` (mount WebDAV).
- Symlink del repo (`memory/MEMORY.md`, `archivio/CLAUDE.md`) non si risolvono su Windows (`core.symlinks=false`) — leggere sempre i file fisici diretti su Ufficio.