feat(dialer): CPS Limiter + Predictive Dialer Engine

Fecha agente.md secao 72-86 (motor preditivo) e 77-79 (CPS distribuido,
reserva de leads, lock de campanha). Uma campanha RUNNING agora origina
chamadas sozinha, respeitando capacidade de agentes, CPS hierarquico e
taxa de abandono — sem intervencao manual.

Deliberadamente fora do escopo (agente.md secao 72: "nao e' so' `for lead
-> originate`"): mod_avmd (opcional), callbacks agendados, disposicoes de
agente — ficam pra fase CDR.

## Novo servico apps/predictive-dialer

Mesmo padrao arquitetural de fs-events/fs-config: Node standalone em
Docker, ESL propria, tick a cada 2s sobre tenants ativos x campanhas
RUNNING/WAITING_SCHEDULE.

- Lock de campanha (dialer:campaign:{id}, secao 79): TTL/ownership/
  renewal/safe-release via Lua compare-and-delete.
- CPS distribuido (secao 77, 62): token bucket janela 1s, hierarquia
  GLOBAL/TENANT/TRUNK/CAMPAIGN numa unica chamada Lua atomica — nivel
  esgotado bloqueia todos SEM incremento parcial dos que passariam.
- Reserva atomica de leads (secao 78): FOR UPDATE SKIP LOCKED dentro da
  mesma transacao withTenantContext.
- CallAttempt/CampaignStats (schema novo): state machine da chamada
  (secao 82) + EWMA (secao 75) de answer_probability/average_answer_delay/
  average_talk_time/abandon_rate por campanha.
- Capacidade em tempo real + pacing (secao 73-76, 84-85): conta agentes
  por estado via Tier->Agent.state, previsao de liberacao (horizonte
  unico de 15s, simplificacao documentada dos 4 buckets da especificacao),
  controle de abandono reduz pacing progressivamente, nunca origina sem
  capacidade prevista.

## Modo simulacao (secao 185-186)

DIALER_SIMULATION=true (default, ja estava no .env desde o inicio da
sessao) sorteia ANSWER/BUSY/NO_ANSWER/FAILED em software, sem PSTN real.
So' quando ANSWERED e' que uma chamada sintetica (null/dummy, sem PSTN)
entra na fila real via mod_callcenter de verdade — escolha deliberada pra
maximizar codigo real exercitado em vez de simular tudo em memoria. Os
identificadores da secao 81 (b2bcall_tenant_id/call_id/attempt_id/
campaign_id/lead_id) vao como channel variables nessa perna, entregando
tenantId real no WebSocket sem fan-out.

Real Outbound Safety (secao 186): as duas flags checadas no boot, nunca
ativadas automaticamente — caminho PSTN real implementado mas nunca
exercitado (sem trunk/operadora real neste laboratorio).

## Dois bugs reais achados e corrigidos testando esta fase

- Perna sintetica (null/dummy) nao tem midia do outro lado — nunca
  desligava sozinha depois de bridgear com um agente. Corrigido com
  hangup agendado via uuid_kill no talk_time simulado.
- Corrida entre queue:sync e tier:sync (dois canais Redis independentes,
  sem ordem garantida): atribuir tier logo depois de criar a fila podia
  rodar tier add antes do queue reload terminar ("-ERR Queue not found!",
  erro real, diferente do ja conhecido "already exist"). Corrigido com
  retry curto (ate 3 tentativas) em agent-sync.ts::addTierWithRetry.

## GET /campaigns/:id/stats

Secao 227.7 "visualizar pacing" — CampaignStats + agentes por estado +
calls em andamento, sem esperar a fase Frontend.

Verificado ponta a ponta: campanha RUNNING originando 3 tentativas por
tick, outcomes simulados corretos com retry agendado (BUSY 15min/
NO_ANSWER 60min/FAILED 30min), uma tentativa ANSWERED completando o ciclo
real inteiro (fila -> agente -> bridge -> hangup -> EWMA atualizada),
stop nao derruba chamada ativa (secao 66), calls_answered=3 confirmado no
`queue list` do FreeSWITCH. CPS limiter e lock de campanha testados
isoladamente (hierarquia sem incremento parcial, ownership nunca
roubado). typecheck do workspace inteiro limpo.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X1HxY46WGU4G1zmVDNKcWw

TODO.md

@@ -317,12 +317,69 @@
 - [ ] `PredictiveDialerEngine` (secao 72-86) — dados em tempo real, EWMA,
       CPS distribuído, reserva atômica de lead, lock de campanha,
       originate via bgapi, state machine da chamada, controle de abandono,
-      retry — fase própria, não iniciada
+      retry — implementado na PHASE 16
 - [ ] Wizard visual de importação (upload de arquivo) — fase Frontend
 - [ ] Relatório de campanha (secao 160) — depende de CDR
 
-## PHASE 16+ — ver `agente.md` seções 72 em diante (Predictive Dialer Engine,
-CDR, Recordings, AI, Billing, Frontend, Reports, Security, Tests)
+## PHASE 16 — CPS Limiter / Predictive Dialer Engine (agente.md secao 72-86, 77-79)
+- [x] Novo serviço `apps/predictive-dialer` (mesmo padrão de fs-events/
+      fs-config: Node standalone em Docker, ESL própria, tick a cada 2s
+      sobre tenants ativos x campanhas RUNNING/WAITING_SCHEDULE)
+- [x] Lock de campanha (`dialer:campaign:{id}`, secao 79): TTL, ownership
+      token, renewal, safe release (Lua compare-and-delete) — testado
+      isolado, outro dono nunca rouba nem renova o lock de quem já tem
+- [x] CPS distribuído (secao 77, 62): token bucket janela de 1s (Lua
+      atômico), hierarquia GLOBAL/TENANT/TRUNK/CAMPAIGN numa única chamada
+      — testado isolado, nível esgotado bloqueia todos SEM incremento
+      parcial dos que passariam
+- [x] Reserva atômica de leads (secao 78): `FOR UPDATE SKIP LOCKED` raw
+      SQL dentro da mesma transação `withTenantContext`
+- [x] `CallAttempt`/`CampaignStats` (schema novo): state machine da
+      chamada (secao 82) + EWMA (secao 75, alpha=0.25) de
+      answer_probability/average_answer_delay/average_talk_time/
+      abandon_rate, persistida por campanha
+- [x] Capacidade em tempo real + pacing (secao 73-76, 84-85): conta
+      agentes por estado via Tier->Agent.state, previsão de liberação
+      simplificada (horizonte único de 15s em vez dos 4 buckets da
+      especificação), controle de abandono reduz pacing progressivamente,
+      nunca origina sem capacidade prevista
+- [x] Modo simulação (secao 185): DIALER_SIMULATION=true (default) sorteia
+      ANSWER/BUSY/NO_ANSWER/FAILED em software, sem PSTN real. Só quando
+      ANSWERED é que uma chamada sintética (null/dummy, sem PSTN) entra na
+      fila real via mod_callcenter de verdade — maximiza código real
+      exercitado em vez de simular tudo em memória
+- [x] Real Outbound Safety (secao 186): as duas flags
+      (DIALER_SIMULATION=false + ALLOW_REAL_OUTBOUND_CALLS=true) checadas
+      no boot, nunca ativado automaticamente — caminho PSTN real
+      implementado mas nunca exercitado (sem trunk real neste laboratório)
+- [x] **Bug real, achado no teste desta fase**: perna sintética (null/
+      dummy) não tem mídia do outro lado — nunca desliga sozinha depois de
+      bridgear com um agente. Corrigido com hangup agendado via
+      `uuid_kill` no talk_time simulado.
+- [x] **Bug real, achado no teste desta fase**: corrida entre `queue:sync`
+      e `tier:sync` (dois canais Redis independentes, sem ordem garantida)
+      — atribuir tier logo depois de criar a fila podia rodar `tier add`
+      antes do `queue reload` terminar ("-ERR Queue not found!", diferente
+      do já conhecido "already exist"). Corrigido com retry curto em
+      `agent-sync.ts::addTierWithRetry`.
+- [x] `GET /campaigns/:id/stats` (secao 227.7 "visualizar pacing"):
+      CampaignStats + contagem de agentes por estado + calls em andamento
+- [x] Testado ponta a ponta: campanha RUNNING originando 3 tentativas por
+      tick, outcomes simulados corretos com retry agendado, uma chamada
+      simulada-ANSWERED completando o ciclo real inteiro (queue -> agente
+      -> bridge -> hangup -> EWMA atualizada), stop não derruba chamada
+      ativa (secao 66), calls_answered=3 confirmado no `queue list` do
+      FreeSWITCH ao final
+- [ ] Previsão de 4 buckets (5/10/15/20s, secao 74) — simplificado pra um
+      único horizonte de 15s
+- [ ] mod_avmd (secao 87), callbacks agendados (secao 88), disposições de
+      agente (secao 89) — fora do escopo, ficam pra fase CDR
+- [ ] CPS a nível de trunk — só aplica quando o caminho PSTN real rodar
+- [ ] Relatório de campanha (secao 160), TME/TMA/Service Level/Abandon
+      Rate agregados — dependem de CDR
+
+## PHASE 17+ — ver `agente.md` seções 87 em diante (CDR, Recordings, AI,
+Billing, Frontend, Reports, Security, Tests)
 
 ---