Caching & performance

Be fast without being wrong. Reuse the facts that rarely change, re-fetch the ones that move, and let the server do the waiting.

Cache what is stable, not what moves#

Cache identity in the agent process and refresh only on unauthorized, active_org_required, forbidden_scope, or quota_exceeded. Re-fetch capabilities only after repost update or when a needed command is absent.

Prefer waits and gates to polling#

A wait command blocks server-side and costs one round-trip instead of many. A gate checks the current state once and returns a typed result. Reach for these before writing any loop:

• expect / tail: wait for events (Wait for events).
• replay wait: wait for a replay job (Replay deliveries).
• health --fail-on: gate on the current health threshold (Diagnose webhooks).

When you must poll#

When no wait command fits, poll deliberately:

• Back off exponentially: 1s, 2s, 4s, 8s. Never a tight loop.
• Stop on terminal codes: validation_failed, active_org_required, forbidden_scope, and quota_exceeded never succeed on retry.
• Retry only rate_limited (exit 6) and upstream_unavailable (exit 1), backing off further on rate_limited until the server limit resets.
• Bound every poll with a deadline so an agent can never spin forever.

Continue#