Preview refresh should not mask provider failures as stale OIDC auth

[cbusillo]

Context

The SellYourOutboard generic-web proof exposed a confusing failure mode in POST /v1/drivers/generic-web/preview-refresh.

The GitHub workflow sends a valid OIDC-authenticated request. When provider work runs for about five minutes, the client eventually reports:

401 authentication_required
A valid GitHub OIDC token or browser session is required.

That appears to happen after the useful HTTP window has elapsed and the caller retries with the original short-lived GitHub OIDC token. The visible failure then becomes auth-shaped even though the real issue was provider/health/ingress related.

Need

Launchplane should return or record the real preview refresh result, not a stale-token retry symptom.

Candidate work

• Avoid retrying long mutation requests with an already-issued GitHub OIDC token.
• Consider making preview refresh an accepted async operation with a record id and poll/read endpoint.
• Ensure provider failures are persisted and surfaced in PR feedback/workflow summaries.
• Bound synchronous route execution below proxy/token timeout if we keep the current request model.

Related

• Launchplane PR Default preview apps to DNSRR endpoint mode #93
• Launchplane issue Generic web previews should validate public preview ingress #94
• SellYourOutboard PR Harden Harbor-managed VeriReel preview provisioning #10

Current Status

State: Complete. PR #245 persisted generic-web preview refresh provider results into Launchplane preview/generation records, added optional anchor PR metadata for refresh requests, rejected unparseable preview slugs before provider mutation, and documented the refreshed route contract. Merged to main at ba95add and deployed successfully on 2026-05-04.
Next action: Closed as complete; continue #241 by deciding/fixing #94 and #97 preview proof scope.
Blocked by: Nothing.
Last verified: 2026-05-04 after PR #245 post-merge CI/Security/CodeQL and Deploy Launchplane passed.

Relationships

• Blocks Prove backend/API product workflows before UI rewrite #241 until fixed or explicitly deferred from the first rebuilt UI slice.

Validation

• Local: uv run python -m unittest passed 668 tests.
• Local: uv run --extra dev ruff check . passed.
• Local: uv run --extra dev ruff format --check control_plane/service.py control_plane/workflows/generic_web_preview.py tests/test_service.py passed.
• Local: uv run --extra dev mypy control_plane tests passed.
• Local: pnpm --dir frontend validate passed.
• Local: git diff --check passed.
• PR Persist generic-web preview provider results #245 checks passed: CI, Security, CodeQL, frontend validation, tests, static checks, container scan, workflow lint, secret scan.
• Post-merge main checks passed for ba95add: CI, Security, CodeQL, Deploy Launchplane.
• Note: repo-wide uv run --extra dev ruff format --check . still reports pre-existing unrelated formatting drift in untouched files.

[cbusillo]

Completed by PR #245, merged to main at ba95add. Generic-web preview refresh now persists provider pass/fail results as Launchplane preview/generation evidence, accepts optional anchor PR metadata, and rejects unparseable preview slugs before provider mutation. Validation and post-merge deploy passed on 2026-05-04.