Shared phone numbers need labels, liveness, and honest accounting

A phone number is shared infrastructure with a carrier-tracked reputation; the cheapest reliability features we've shipped are a purpose tag, a heartbeat, and a duration that tells the truth.

Where the field is

In outbound voice, the phone number itself has become the scarce, reputation-bearing resource. A "Spam Likely" label drops answer rates by 60 to 80 percent overnight, and there is no single appeals desk: AT&T runs Hiya, T-Mobile runs First Orion, and Verizon runs TNS Call Guardian, three separate reputation models with three separate databases. Remediation is a product category now (roughly $10 per number per month, with typical label removal in 2 to 3 business days), and branded caller ID is a separate system from spam labeling, so a call can display your brand and still carry the label.

The economic answer everyone converges on is pooling: lease a set of DIDs, rotate outbound traffic across them, watch their health. Platforms increasingly pitch number-health management and bring-your-own-number as differentiators, because a burned DID at scale is real money. But pooling creates a bookkeeping problem the vendor posts skip: once numbers are a fungible pool, the system stops knowing what any given number is FOR. The DID leasing as an outbound campaign caller ID, the number answering callbacks to that campaign, and a shop's actual intake line are operationally three different things with three different blast radii, and if your data model can't tell them apart, neither can your on-call engineer at 2am.

What we shipped against it

One recent olive-sonic merge shipped three small pieces of number-pool hygiene. None is clever. Together they make a shared pool operable.

First, numbers got a purpose. PhoneNumber.purpose tags each DID as outbound-pool (a leased campaign caller ID), callback (answers business callbacks to a campaign number), intake (a shop's inbound line), or general (the historical default). The platform sets it at create or import time. It is deliberately advisory: the engine classifies and surfaces it but does not gate on it, because enforcement belongs to the platform that owns routing policy, not the engine that executes calls. The honest limit: an advisory tag prevents confusion, not misuse.

Second, calls got a liveness signal. The worker stamps a heartbeat on the call record every 15 seconds while the job process is alive. A sweeper finalizes any "ongoing" call whose heartbeat has gone stale for about 2.5 minutes, instead of letting it sit until the 45-minute ceiling. We added this after watching a native-library segfault kill a worker mid-call: the process died, the call record stayed "ongoing" for the full ceiling, and on a pooled number a zombie call is a DID held hostage. Calls that never wrote a heartbeat at all get a separate, shorter cutoff. Long legitimate calls are protected: anything with a live heartbeat is exempt from the ceiling backstop.

Third, dead calls got honest durations. When the sweeper finalizes a dead call, duration is computed as last heartbeat minus start, which approximates real talk time to within 15 seconds. The previous behavior, wall-clock now minus start, fabricated 45-minute "durations" for calls nobody was on, and downstream billing reads this field. No heartbeat means duration zero: unknown must be free. The same merge also added end_call_phrases, deterministic hangup when the agent speaks its farewell line, because models are flaky about actually invoking the end-call tool after saying goodbye, and a call that never ends is the zombie problem again by another route.