docs: ack-tracking sectie + gecorrigeerde ack-semantiek in README

README.md

@@ -121,7 +121,7 @@ src/
   dailyStats.js         # Dagelijkse aanvraag-teller
   dienstService.js      # JSON lookup en PNG bestandspaden
   whatsappApi.js        # WhatsApp API client (bericht + afbeelding)
-  pinnedMessageService.js  # Vastgezet welkomstbericht beheer
+  ackTracker.js         # Ack-tracking: hangende media detecteren
   telegramBot.js        # Telegram watchdog (apart process, health checks)
 ```
 
@@ -143,6 +143,47 @@ Bij elke interactie met de groep controleert de bot of het pinned bericht nog be
 - **Restart-loop preventie**: systemd `Restart=always` met `RestartSec=5`
 - **Webhook fout**: wordt gelogd in de logs
 
+## Ack-tracking (ghost-send detectie, sinds 2026-09-24)
+
+Sommige mediabestand-verzendingen keren `success` + message-ID terug maar worden nooit
+**bezorgd**: ze blijven op één grijs vinkje hangen (ack 1) en de ontvanger ziet niets
+aankomen. Dit is een bestand×ontvanger-interactie in WhatsApp's mediaverwerking (niet de
+sessie — zie AGENTS.md). De bot detecteert dit via `message_ack`-events en waarschuwt.
+
+### Hoe het werkt
+
+1. **Vereiste:** wwebjs-api .env — `message_ack` uit `DISABLED_CALLBACKS` halen
+   (staat er sinds 2026-09-24 niet meer in) + container herstarten.
+2. `sendImageMessage` registreert elke verzending (`src/ackTracker.js`) met message-ID,
+   chat en bestandsnaam; de webhook (`message_ack` in `messageHandler.js`) update de ack.
+3. Bij **ack ≥ 2** (bezorgd op apparaat) wordt de tracking verwijderd.
+4. Blijft een bericht **> `ACK_STUCK_TIMEOUT_MS` (5 min) op ack < 2** → éénmalige
+   admin-notificatie (WhatsApp → Telegram-fallback) met bestandsnaam + chat en het advies
+   "opnieuw renderen + bezorgtest". Er volgt **geen sessie-herstart** (die helpt niet bij
+   een ack-1-hang) en geen resend naar de aanvrager.
+5. **Pruning:** entries worden na `ACK_PRUNED_AFTER_MS` (30 min) opgeruimd; de check-loop
+   is **activity-driven** (loopt alleen zolang er tracking open staat, geen 30s-polling
+   in rust).
+
+### Ack-semantiek (wwebjs 1.34.7)
+
+| ack | Betekenis |
+|-----|-----------|
+| 0 | onbekend/nete verstuurd |
+| 1 | verstuurd naar server (één grijs vinkje) — **hangt hier** |
+| 2 | bezorgd op apparaat (twee vinkjes) |
+| 3 | geopend/gelezen (blauwe vinkjes) |
+
+### Configuratie
+
+| Variabele | Doel | Default |
+|-----------|------|---------|
+| `ACK_STUCK_TIMEOUT_MS` | Leeftijd zonder ack 2 = stuck | `300000` (5 min) |
+| `ACK_PRUNED_AFTER_MS` | Stale tracking opruimen | `1800000` (30 min) |
+| `ACK_CHECK_INTERVAL_MS` | Checkinterval (alleen actief bij pending) | `30000` |
+
+Opvallende logregels: `[ack] track …`, `[ack] delivered ack=…`, `[ack] pruned …`.
+
 ## Spam protectie
 
 Elke gebruiker kan maximaal `MAX_REQUESTS_PER_DAY` (standaard 5) diensten per dag opvragen. Bij overschrijding krijgt de gebruiker een melding. De teller wordt dagelijks automatisch gereset (bij de eerste request na middernacht).