Rate limits and concurrency

TOVIO is built for concurrent clients. What follows is what actually governs an automated one — and where it does not, this article says so rather than inventing a number.

Compare-and-set, not locks

Proposal and audit writes use compare-and-set against a version. Two clients racing means one gets a conflict (HTTP 409) — re-read the current version and retry, rather than failing outright. Automation should expect and handle this rather than serialising everything through one worker.

Sync converges

Lane refs are CRDTs over a hybrid logical clock, so many replicas syncing concurrently converge without a central lock. Concurrency is the design, not the exception.

Metered, not throttled

No plan caps how many agent sessions may run at once. Hosted agent usage is metered instead: one admitted session grant is one billable session, and replay or heartbeat renewal within that grant is not a new session. Reuse a session rather than reconnecting per task — that is a cost decision, not a concurrency limit. Each plan does include a monthly session allowance; the pricing page is the system of record for the current figures, and this article deliberately does not restate them.

Where limits do bite

• Hosted CI minutes are an allowance. Each plan includes a monthly grant — flat on some plans, per-seat with a floor and a ceiling on others — and the free plan includes none. Beyond it, minutes meter as overage. A refused compute reservation is TVO-CI-005, which reuses the plan-limit refusal TVO-FORGE-026 and HTTP 402.
• Network admission policy can refuse a connection by source address before authentication even happens — TVO-NET-001, HTTP 403. Deny wins; an empty allow-list means allow-all. This applies uniformly across native TLS, HTTP-framed sync, the REST sync routes, the web edge, and git smart-HTTP.
• Every CI-bridge invocation is time-bounded — 15 minutes by default, 60 maximum. A long operation needs an explicit timeout-seconds, not a retry loop.

The GitHub-compatible surface

The façade emits X-RateLimit-Limit, -Remaining, and -Reset headers. Where a deployment enforces no limit they are still present with non-misleading values, because real clients assert on their presence — so read them, but do not infer a limit exists from the headers alone. Pagination is ?page=&per_page= with RFC 5988 Link headers; per_page defaults to 30 and caps at 100. Conditional requests work: send If-None-Match and honour 304 rather than re-fetching.

Do not poll tightly

tovio sync --watch keeps syncing on an interval (floored at 5 seconds) using the saved origin, and tovio change watch <chg:…> --remote <host:port> follows a change's Forge events with a de-duplicating cursor. Both exist so you do not have to write a polling loop. Note that change watch fails closed without --remote rather than pretending to watch nothing.

Back off on transport failures

TVO-SYNC-* is the retryable family. Exponential backoff with jitter; do not hammer a Forge that is already struggling.

Scale evidence is open

Behaviour at the declared ceilings is not yet independently proven — that is one of the open Phase 5 gates. If you are planning something large, say so rather than assuming.