LKMA-198: Add pppd supervisor bridge

[nicolasumaras]

Summary

• add pppd supervisor for pty-opened control events, per-pid secrets files, notify JSON diagnostics, and clean shutdown
• bridge PPP credentials into chap/pap secrets and wire pppd lifecycle through session/server termination
• remove synthetic PPP LCP probe audio and document pppd runtime defaults

Verification

• npm test -- --test-reporter=spec

[nicolasumaras]

Code Review — LKMA-198: pppd supervisor and chap-secrets bridge

Verdict: APPROVED (posted as comment — GitHub blocks self-approval on this repo)

Reviewed head 547aa9b0ec07d3fb7e4c2d32748e07d9d3b5c807 on branch lkma-198-pppd-supervisor.

Checklist

Item	Result
Branch is task-specific (not reused)	✅ lkma-198-pppd-supervisor — one commit ahead of main
CI test check at head	✅ SUCCESS (32/32, 2026-06-26T00:45:28Z)
Local test run	✅ 32 pass / 0 fail
PR mergeable, no conflicts	✅ MERGEABLE / CLEAN
All ticket deliverables present	✅

Deliverables verified

• src/pppd-supervisor.js (310 lines): spawns pppd on pty-opened with the full required option set — nodetach, nodefaultroute, noccp, require-chap (configurable to require-pap), local:client address pair, ms-dns per server, mtu 1500, lcp-echo-interval 30, lcp-echo-failure 4, plus lcp-restart, lcp-max-configure, ipcp-restart, ipcp-max-configure, connect-delay for high-latency links.
• Per-PID secrets file: shell wrapper uses $$ (== child.pid) and polls until the file appears before exec-ing pppd. Node writes synchronously via renderChapSecrets right after spawn. No race gap. Permissions enforced at 0o600.
• IPCP-open/close diagnostics: normalizeNotifyEvent maps IPCP-open/ip-up → ipcp-open, surfaced in session.pppd.state — satisfies media.modem.ppp.state == 'ipcp-open'.
• Clean shutdown: stop() sends SIGTERM; exit handler removes session dir with { recursive: true, force: true } (safe against double-cleanup). terminate() calls stopPppd before releasing the address lease.
• Synthetic PPP-frame logic deleted: PPP_LCP_CONFIGURE_REQUEST, buildPppFrame, pppFcs16, buildPppProbeFrame, ppp-lcp-probe state, DEFAULT_PPP_MARK_HZ/SPACE_HZ — all gone.
• deploy/sipfax.env.example: SIPFAX_PPPD_COMMAND, SIPFAX_PPP_AUTH, SIPFAX_PPP_NOTIFY_SCRIPT documented.
• Tests: credential rendering (0o600 mode, quoting), arg coverage, supervisor lifecycle (per-PID file, notify JSON, SIGTERM + cleanup), session controller wiring, server control-event routing.

Non-blocking findings (follow-up welcome)

1. dnsServers in PppdSupervisor constructor is never used — PppSessionController.startPppd always passes its own copy, making the supervisor's stored value dead config.
2. noauth absent from pppd args — if a client requests server auth, pppd may fail. Acceptable for current scope; can be added if interop issues arise.
3. sleep 0.02 (fractional) in shell wrapper works on Debian GNU coreutils (target) but not BusyBox.

All deliverables match the ticket. Approved for merge.