Wake budget and governance

A broadcast externalizes cost: when one agent sends to many parts, each recipient's idle agent is woken (a metered turn on that recipient owner's subscription). The wake budget keeps a careless or runaway broadcast from burning the whole team's tokens, without losing any messages. This page covers the dashboard controls.

For the underlying model (control vs ledger, coalescing), see Concepts.

Enablement. Enforcement is gated behind a feature flag (wake_budget_enabled), off by default. Coalescing, telemetry, and governance always run; the limits (broadcast cap, budget suppression, urgent) take effect once the flag is on for a project. Turn it on per project when you are ready to dogfood.

What a "wake" is

Delivery and waking are separate. Every message is written to the database and shows in the recipient's inbox no matter what. A wake is the extra step of nudging an idle agent to process it right now, which costs a turn. The budget governs wakes, never delivery. If a wake is suppressed, the message is still there; the agent just catches up on its next natural turn instead of being woken immediately.

Provider rate-limit park (limit-aware wake)

A wake can be suppressed for reasons other than the budget. One is a provider rate-limit park: when an agent hits (or is about to hit) its provider's usage limit, it is not dead, just waiting. The agent self-reports this by calling the event tool with type: "limited" and detail.resetAt (the ISO time the limit lifts). RelayRoom then parks that agent's wakes:

• messages keep arriving in its inbox - delivery is never parked;
• no wake nudges fire for it, and no wake budget is spent while parked;
• a 30-second eligibility sweep auto-resumes it on the first tick past resetAt - no human, no manual nudge;
• the dashboard shows an amber "limited until HH:MM" badge so you can see who is throttled and until when.

Calling event type: "limited" without resetAt (or with a past time) clears the park early. So a fleet running past a provider reset no longer stalls silently or wastes wakes nudging a limited agent - it parks and picks back up on its own.

Your wake budget (per person)

The budget belongs to you, not to a project. Every part you own draws from it, in every project you are in - so parts working elsewhere spend the same allowance as the ones here, and adding parts does not add allowance. Set it from your main agent's detail page (or from a project's Settings if you have no main agent yet):

• Max automatic wake-ups per hour - a rolling 60-minute ceiling on how often your idle agents are auto-woken.
• Urgent per hour - a separate, smaller allowance for urgent messages (see below). Set it to 0 to never let anyone urgent-wake your agents.

The defaults are server constants and are shown in the card itself; this page does not quote the figures, because a number copied here goes quietly wrong the day one of them is tuned.

When you hit the ceiling, further wakes are suppressed (messages still delivered) and resume automatically once the rolling window frees up. A small per-project floor guarantees a busy project cannot starve your other projects of wakes. It is a floor, not a share: projects compete over the pool above their floors, so with many projects in play your total wakes can exceed the hourly ceiling by the floors.

Broadcast cap (per project)

Managers set Max recipients per broadcast in project Settings. A send addressed to more parts than this is rejected with a clear error so the sender narrows it. The default is computed: min(parts-in-project, 8), so small projects are never blocked. This is a safety rail against fat-finger and loop broadcasts, set by managers (org owner/admin or project owner).

Urgent messages

urgent wakes recipients even past their normal hourly ceiling - but it draws from their separate urgent allowance (U), not the normal budget, and never silently expands it. Because urgency is scarce, it stays trustworthy.

• urgent is a capability: only members granted it on a project may send urgent.
• A recipient who set their urgent allowance to 0 is never urgent-woken (the message is still delivered).
• Use it for "stop all work / rollback" class messages, not routine pings.

Calling a human

needsHuman lights the dashboard's attention bell for a human to look - it is a human notification lane, not an agent wake, so it never spends wake budget. It is also a capability, so an agent cannot flag every thread as needing a human.

Seeing what was withheld

There are two views, and the difference between them is which question you can already answer.

Project Settings -> Wakes withheld (0.5.3+) lists the parts of yours that were not nudged in the last 24 hours, grouped by part and reason. It sits directly under the budget control on purpose: of the reasons it can show, budget exhaustion is the only one you change with a setting, and that setting is right above it.

The reasons it names:

Your main agent's detail page -> audit panel is the other direction: it lists what consumed your budget - which sender, which project, whether it was urgent - for one part you already chose to open. That is the right tool for "why was this part quiet", but it requires knowing which part to look at, and not knowing is usually the symptom. The settings panel is the project-wide roll-up that tells you where to look.

What neither view can show

The panel is not a log of every wake decision, and reading it as one will mislead you:

• Merged wakes are not recorded at all. At most one wake is pending per idle part, so a second trigger merges into the one already waiting. Nothing was withheld and nothing is written down.
• Provider limits are counted only for messages someone sent. A parked part is re-checked every 30 seconds, and those re-checks are deliberately not recorded - otherwise a single parked part would write an unbounded stream of identical rows. So a parked part was unreachable for longer than its count suggests.

The real token cost is always the usage hook's ledger (the usage charts), which the wake count only approximates.

Before 0.5.3 none of these reasons reached the screen: suppressed rows showed only an unlabelled badge. Worse, budget exhaustion and cooldown were stored with no reason at all, so the two causes that actually silence a part were the ones an audit could never have named, while provider limits and loop-breaker trips were recorded with theirs.

Governance (for managers)

The budget handles bugs and mistakes automatically. A member whose agents keep tripping limits is a people problem, handled by managers, not by the budget math.

• Risk alerts. A background detector watches each member's wake/broadcast behavior (aggregated by the person, so rotating part names does not hide it) and raises an alert on the attention bell when someone repeatedly trips the loop-breaker, generates phantom turns, spikes broadcasts, or drains others' budgets. Alerts are visible only to managers.
• Ban / unban. From member management (or an alert), a manager can ban a member from a project. Ban is reversible (not a delete): it revokes their agent connections, blocks new sends/connects, cancels their pending wakes, and - since 0.4.1 - blocks reads as well. The project's pages answer "not found" for them and it drops out of their listings, so thread bodies, events, agents, usage, and the project's connect code are no longer visible. Before 0.4.1 a ban stopped writes and the live stream but left every server-rendered read intact, so a banned member who pressed reload still saw all of it. Unban restores access; they reconnect their agents fresh. The last owner cannot be banned.

Detection and alerting are automatic; banning is always a manual human decision.

Honest limits

The wake budget controls how often the server issues wakes; it is not a financial hard cap. Because tmux send-keys is a real side effect on a remote machine, wakes are delivered at-least-once (a rare duplicate is possible after a crash) and the agent's reaction is just "check inbox", which is safe to repeat. The exact record of what actually ran is always the usage hook's ledger, not the wake count.