docs(presence): 90s TTL is documented as 3× a 30s heartbeat, but the agent harness heartbeats at 60s (real margin 1.5×)

[tlongwell-block]

Summary

Three places document the presence TTL as "3× the 30s heartbeat." The agent harness publishes its presence heartbeat every 60s, so for agents the real flap margin is 1.5×, not 3× — one missed heartbeat leaves 30s of slack, two are fatal. The desktop client does heartbeat at 30s, so the comments are correct for one publisher and wrong for the other, and a fourth doc comment states the TTL itself incorrectly.

Found while truth-auditing presence claims for the remote-agents work (docs/remote-agents.md, PR #3748). This is a comment/doc-accuracy bug with a real behavioral question behind it — not a functional break — but the wrong margin is the kind of number someone sizes a timeout against later.

All line numbers below are at b4f4ed1a67ce340d9709ca32f3b47dd09cd25dea on origin/main's history, verified with git rev-parse HEAD in the checkout that produced them.

The actual values

What	Where	Value
Redis TTL	crates/buzz-pubsub/src/presence.rs:16	PRESENCE_TTL_SECS = 90
Agent heartbeat	crates/buzz-acp/src/lib.rs:1583	Duration::from_secs(60)
Desktop heartbeat	desktop/src/features/presence/hooks.ts:18	PRESENCE_HEARTBEAT_INTERVAL_MS = 30_000

So the same 90s lease is renewed by two publishers at different rates. 90/30 = 3× for desktop; 90/60 = 1.5× for agents.

Four wrong statements

1. crates/buzz-pubsub/src/presence.rs:4-5 — "TTL is 3x the 30s heartbeat interval so a single missed heartbeat doesn't cause presence flap."
2. crates/buzz-pubsub/src/presence.rs:15 — "3x the 30s heartbeat — single missed heartbeat won't cause presence flap."
3. ARCHITECTURE.md:450 — "90-second TTL (3× the 30-second heartbeat interval). Single missed heartbeat does not cause presence flap."
4. crates/buzz-pubsub/src/lib.rs:331 — "Set presence with 60s TTL. Call on connect and every 30s heartbeat." The TTL is 90s, not 60s. This one is wrong about the constant it delegates to, in the direction that makes the margin look worse than it is — likely a stale survivor of an earlier pair of numbers.

Note that 1–3 are still literally true of the desktop client. The claim they make that fails is the safety conclusion — "a single missed heartbeat won't cause flap" is a promise about all presence publishers, and it is 30s of slack away from being true for agents.

Why the margin matters, not just the comment

For an agent: last successful publish at t=0, next attempt at t=60. If that publish fails or is delayed past t=90 — relay reconnect with backoff (ARCHITECTURE.md:448: 1s→30s exponential, resets only on clean stream end), rate-limit skip, a slow SET — presence expires and the agent goes dark while alive. The retry isn't until t=120.

The harness heartbeat also fires from the main select! loop (crates/buzz-acp/src/lib.rs:2301-2320), and interval_at starts the first tick at now + 60s rather than immediately; startup is covered separately by the eager publish at :1510, so this is about steady state, not boot.

I did not find field reports of spurious agent-offline flaps, and I did not go looking in logs — so treat the impact as reasoned, not observed. #877 ("fix(presence): clear on disconnect, fix heartbeat/TTL", CHANGELOG.md:1198) is prior art on this exact pair of numbers and probably worth reading before choosing.

The decision this needs (why I'm filing rather than fixing)

Which number is wrong is a product/ops ruling, not a comment edit:

• (a) Comments were right, the interval drifted. Take the agent heartbeat to 30s, restoring a uniform 3× margin. Cost: 2× presence publish volume from agents.
• (b) 60s is intentional (agents are chattier per-publish than a browser tab and the relay pays for it). Then fix all four comments to state the real margin per publisher, and say plainly that agents tolerate zero missed heartbeats with 30s to spare.
• (c) Decouple. Derive the TTL from the publisher's declared interval instead of hardcoding a constant that two callers renew at different rates. Most correct, most work, and probably overkill for two publishers.

My weak preference is (b) plus a one-line note at the constant naming both publishers — the invariant worth documenting is "TTL ≥ 1.5× the slowest publisher's interval," which makes the next divergence visible instead of silent. But I have no evidence about relay publish cost, and whoever owns relay load should overrule me if 30s is cheap.

Whichever lands, the fix should make the two intervals reference each other, because the failure mode here is that they can drift independently and only a comment notices.

[webdevtodayjason]

Observed data for the agent margin, since the issue treats the impact as reasoned rather than observed. I run a self-hosted pilot (compose-derived stack, ghcr.io/block/buzz:main, digest 70beb871, relay up 4 days) that happened to have both publisher classes live at once: the desktop app and one desktop-managed buzz-acp agent on a builtin persona with default config, so the 60s harness heartbeat from lib.rs:1583.

I sampled redis-cli TTL on both presence keys every ~5s for 5 minutes (01:21:50 to 01:26:58 UTC, 2026-07-31). One full agent cycle from the capture:

01:22:42  desktop=79  agent=90
01:22:47  desktop=87  agent=84
01:22:52  desktop=81  agent=79
  ...decays ~5s per sample...
01:23:34  desktop=86  agent=37
01:23:39  desktop=81  agent=32
01:23:45  desktop=76  agent=87

Agent key: clean sawtooth, five full cycles in the window. Renewal spacing 57 to 63s (sampling granularity around 60.0s), and remaining TTL bottomed at 32 to 35s in every cycle right before renewal. With 5s sampling that's a true trough of about 30s. So the 1.5x margin is exactly what production shows: one missed or delayed beat leaves about 30s and the next attempt is 60s away.

Desktop key: never below 73s remaining in the same window, renewing every 10 to 17s, noticeably more often than the documented 30s beat (renew on activity or multiple sources, I didn't chase it). In practice the asymmetry between the two publishers is wider than the 90/30 vs 90/60 math suggests.

On the "no field reports" point: 96 hours of relay logs at default level contain zero presence lines. Expiry is just a Redis TTL lapsing, so an agent flapping offline leaves no server-side trace. Nobody would have filed a report unless they were staring at the sidebar when it happened. To be clear, I observed the margin, not a flap; no beats were missed during the capture.

One input for the (a)/(b) cost question: on this deployment presence renewal is a WS publish plus a Redis SET per beat. Halving the agent interval takes my per-agent cost from 1 write a minute to 2. Even at hundreds of agents that's noise next to normal message and typing traffic, so if 60s is only defending publish volume, the cost argument looks thin from the operator seat. Your invariant line is the part I'd most like to see land either way: make the TTL and the intervals reference each other so the next drift is a review-time fact instead of a comment nobody rereads.

Happy to run a longer capture, or rerun this after any change if that helps.

[Chessing234]

looks like this was already fixed on main by #3783 — PRESENCE_TTL_SECS is 180 (3× the 60s agent heartbeat) and desktop also heartbeats at 60s now. happy to close this if that matches what you wanted; the remaining question is just whether ops docs elsewhere still mention the old 90s/30s numbers.

[webdevtodayjason]

Verified on current main and that matches: presence.rs is 180 with the comments naming the 60s beat, ARCHITECTURE.md:450 says 180/60, the pubsub lib.rs doc comment now says 180s/60s, and the desktop derives PRESENCE_TTL_SECONDS = 3 * interval so the client-side pair can't drift silently. Agent margin is now a true 3x.

I also swept for stragglers mentioning the old numbers and came up empty. The remaining 30s hits are different heartbeats (the WS transport ping in ARCHITECTURE.md:204 and the acp self-prompt feature), and the remote-agents doc in #3748 only references presence in its shutdown-drain sequence.

For the record, my capture above was on a pre-#3783 image (digest 70beb871, pulled July 24), so read it as documentation of the old 1.5x margin rather than a contradiction of the new numbers.

Two small things before closing. The relay-side PRESENCE_TTL_SECS = 180 and the harness's Duration::from_secs(60) at buzz-acp lib.rs:1583 are still independent constants in different crates; the comments now name both publishers, which is the practical fix, but the reference-each-other invariant only physically exists on the desktop side. And the 10 to 17s desktop renewals I measured were on the old build; if some of that was renew-on-activity rather than the timer, it may be worth a quick check that #3783 cut desktop publish volume as much as the interval math suggests. Neither blocks closing from my seat.

[Chessing234]

looks fixed by #3783 (merged): desktop heartbeat is now 60s, redis TTL 180s (3×), and the presence.rs / ARCHITECTURE comments match. agent harness was already on 60s. suggest closing this unless you still see a stale doc path i missed.