Preflight agent providers and classify blockers before execution

[shiny-code-bot]

Objective

Classify predictable agent-start failures before committing a spawn slot or beginning expensive work. Surface auth, spend/quota, transient rate limit, prompt size, model-option, agent-capacity, and depth-limit conditions as structured blockers rather than generic agent failures.

Use only safe existing recovery paths automatically. Any compaction, retry, effort adjustment, or fallback must be explicit in status and telemetry; do not silently switch providers or models.

Finish Line

Provider and configuration blockers are classified early, actionable, non-storming, and correctly reflected in agent status.

Current Status

State: Blocked
Next action: Define PreflightResult and rejection classes against the outcome/health contract, then map each provider adapter to offline-preflight or first-call classification.
Blocked by: #434
Waiting for: #434 to stabilize additive outcome/health semantics.
Last verified: July 18, 2026 from recent Claude spend, OpenAI auth, Copilot configuration, and Antigravity prompt/auth failures.

Scope

• In: structured rejection classes, spawn-slot ordering, retry deadlines, existing token refresh/compaction/effort fallback paths, exec/app-server/TUI wording, telemetry.
• Out: silent cross-provider failover, new provider credentials flow, billing changes, broad model-selection policy.

Acceptance Criteria

• Expired or missing auth produces Blocked(auth) and does not retry without a credential refresh path.
• Hard spend/quota exhaustion produces Blocked(quota) with the provider-specific actionable detail.
• Transient rate limits expose retry-after/backoff and become recovered on success without changing the final work outcome.
• Prompt-size rejection compacts only when the existing supported compaction path is available; otherwise it reports prompt_size clearly.
• Unsupported model/reasoning options fail before prompt execution or use an observable safe adjustment.
• Agent/depth capacity does not hold a spawn reservation while blocked and cannot deadlock a waiting parent.
• Human and JSON output expose stable reason kinds and retryability.
• Every automatic recovery emits a health transition; there are no silent fallbacks.

Relationships

This will be attached as a sub-issue of the agent reliability parent and blocked by the terminal outcome/health issue.

Validation

• Provider-stub tests for auth, quota, rate limit, context, and model-option responses.
• Spawn reservation/depth-limit concurrency tests.
• JSONL schema compatibility and TUI snapshot tests.
• Dogfood matrix across configured OpenAI, Claude, Copilot, and Antigravity providers where credentials permit.

Decisions

• Prefer earliest reliable classification; not every provider supports a network-free preflight.
• Do not add feature flags or silently switch providers.
• A blocker is an agent that wants to proceed but cannot; it is not a task failure.

Open Questions

• Which provider checks can be done offline versus only from the first API response?