Operating tips

Practical notes for running agb day to day. For the concepts behind them see Pools and tiers and Run lifecycle.

QuotasCopy Anchor Link

agb reads quota telemetry from agy and sizes the fleet from it.

• Commands that spend quota check it first. plan, preflight (unless --no-coldstart), review and import-brain refresh telemetry and exit 1 with quota telemetry unavailable from agy if they cannot (plan check).
• Caps shrink as quota drains. The effective percentage for each upstream family (Gemini, and Claude plus GPT-OSS) is the lower of the 5-hour and weekly remaining figures (effective percent). Each pool's cap is the smaller of your configured cap and the scaled cap, and recovers as quota returns (cap scaling). Default caps are gemini-flash 8, gemini-pro 4, claude 4, gpt-oss 2 (DEFAULT_CAPS); override them with caps in the plan.
• A depleted pool fails fast. If a pool's cap drops to 0, queued requests for it are aborted rather than left hanging (depleted pool).
• A failed probe stops dispatch. When a quota probe fails, the circuit breaker trips, CRITICAL: Quota probe failed; fleet dispatch suspended is logged, and the state is shared with other agb processes (circuit breaker).

Tips: run large fan-outs early in a quota window; give mechanical tickets tier: "cheap" so they draw from the wide Flash pool; use agb probe to measure real concurrency (see Calibration).

Blocked ticketsCopy Anchor Link

A ticket can end up blocked two ways.

The agent gave up. A builder that prints TICKET-BLOCKED: <reason> consumes a strike, and its worktree is reset to the base for the retry (blocked agent). With two strikes per ticket, a second block fails the ticket with agent blocked: <reason>. A blocked agent almost always means the ticket body is missing context or the scope excludes a file it needs: fix the ticket, not the model.

A predecessor failed. Tickets downstream of a failed ticket never start; they are recorded in the report's failed map as blocked by failed predecessor and shown with phase blocked (predecessor block).

To recover: fix the failing ticket's body or scope, remove tickets that already merged from plan.json (and the edges pointing from them), and run again. Watch progress with agb status --watch or the sidecar dashboard.

Pool drainCopy Anchor Link

agb coordinates concurrent processes through shared lease state. If a crashed or legacy (v0.7) process left leases behind, a new run can refuse to start with a message telling you to run agb pool drain (legacy fleet message, active leases message).

agb pool drain            # repo defaults to .
agb pool drain /path/to/repo

Drain marks the coordinator DRAINING (no new dispatch while it runs), signals remaining workers, settles their leases within a short grace period, and resets the coordinator; it prints a JSON result and exits 0 (drainPools, command). Run it only when no legitimate run is in progress.

Dirty reposCopy Anchor Link

agb run (and agb sweep) refuse to start when the target repo has uncommitted changes, and refuse to merge a ticket if the repo becomes dirty mid-run (start guard, mid-run guard). They also require the plan's base branch to be checked out. Commit or stash first.

What agb actually does to your branch: each merge happens in a separate integration worktree, post-merge gates run there, and the base ref advances only through a compare-and-swap update-ref from the exact commit it started from (integration worktree and CAS: C24, CAS advance: C24). Integration worktrees are named .worktrees/agb-integration-<token8> (integration worktree: C24). A failed integration leaves the base ref where it was and quarantines the candidate under refs/quarantine/; there is no automatic hard reset or clean of your checkout.

AGB_ALLOW_DIRTY=1 skips the clean-tree guard. Use it only when you understand that agb still advances the checked-out branch underneath your uncommitted work.

The warning agb run logs under AGB_ALLOW_DIRTY=1 (and the refusal without it) says exactly that: uncommitted changes are left untouched, but they are not part of the run's base, because builders and gates see only the committed base HEAD.