# ADR-39810: Preflight Org Copilot CLI Billing Detection in the Add-Wizard

**Date**: 2026-06-17
**Status**: Draft

## Context

The Copilot auth-method prompt in the interactive add-wizard presented two options — `copilot-requests` (org Copilot billing seat) and a Personal Access Token — as equally selectable, regardless of whether the target organization actually had Copilot CLI billing enabled. A user could pick `copilot-requests` only to find it did not work for their org. The wizard runs interactively and already knows the target repo (`owner/repo`), so the org login is available before the form renders. The only constraints are that detection must not noticeably slow the interactive flow and must degrade gracefully when the API is unreachable or the caller lacks permission (only org owners receive a `200` from the billing endpoint).

## Decision

We will perform a **preflight REST call** to `GET /orgs/{org}/copilot/billing` before building the auth-method `huh` form, reading the `cli` field to decide form behaviour. When billing is confirmed `enabled`, `copilot-requests` is pre-selected and labelled recommended; when confirmed `disabled` (or any other policy value), PAT becomes the default and a validation guard blocks submitting `copilot-requests`; on any non-200 status, network error, or missing field the result is treated as **inconclusive** (fail-open) — both options stay selectable with PAT as the default and an informational note. The call is bounded by a 3-second timeout. Detection logic is isolated in `pkg/cli/copilot_billing_check.go` with a testable core (`detectOrgCopilotCLIBillingWithClient`) so the network boundary can be unit-tested via `httptest`.

## Alternatives Considered

### Alternative 1: Keep the static form and document the caveat
Leave both options always selectable and rely on documentation or a post-hoc error. Rejected because it leaves the original problem unsolved and pushes the failure to a later, more confusing point in the flow.

### Alternative 2: Validate after submission instead of preflighting
Let the user submit any choice, then call the billing API and reject `copilot-requests` if disabled. Rejected because it makes the form feel broken (accepting a choice then bouncing it); a preflight lets us pre-select the recommended option and surface guidance up front.

### Alternative 3: No API call — infer from local config or skip detection
Avoid the network dependency entirely. Rejected because there is no reliable local signal for org Copilot CLI billing status; only the billing endpoint provides ground truth.

## Consequences

### Positive
- Users are guided to a working auth method up front; invalid `copilot-requests` selections are pre-empted by a default switch plus a validation guard.
- The fail-open policy ensures the wizard never blocks when the API is unreachable, unauthorized, or returns an unexpected shape.
- The network boundary is isolated behind a testable core, giving full unit coverage of the 200/404/403/missing-field/unknown-value/network-error cases.

### Negative
- Adds up to a 3-second latency and a network dependency to an otherwise local interactive step.
- Because only org owners receive a `200`, non-owner users always fall into the inconclusive branch and gain no benefit from detection.
- Introduces coupling to the shape of the `GET /orgs/{org}/copilot/billing` response (`cli` field), which may change upstream.

### Neutral
- `AddInteractiveConfig` gains a `copilotCLIBillingStatus` field (enabled/disabled/empty) threaded through the auth-method step.
- The org login is derived via `strings.Cut(c.RepoOverride, "/")`; detection is skipped when no org segment is present.