feat(aca): resolve Copilot credential automatically via gh auth token

[Jason Robert (jrob5756)]

Summary

Running an aca workflow required hand-creating a fine-grained Copilot Requests PAT and exporting COPILOT_GITHUB_TOKEN — even though the operator is almost always already signed in to GitHub locally. This adds gh auth token as the final step of the DD4 credential chain, so a workflow runs with zero ACA-specific credential setup.

Found and fixed while running examples/aca-coding-agent.yaml end-to-end against a real ACA dynamic-sessions pool.

New precedence (mirrors the Copilot CLI's own documented chain):

COPILOT_PROVIDER_BASE_URL (BYOK)
→ COPILOT_GITHUB_TOKEN / GH_TOKEN / GITHUB_TOKEN
→ gh auth token ← new
→ ProviderError

An explicit token still overrides the ambient gh identity, and a scoped PAT remains the recommendation for CI/service accounts. Every gh failure mode (absent, not signed in, wedged keyring, empty output) means "no token" and falls through to the existing actionable error rather than raising.

Why not read ~/.config/github-copilot/auth.db?

It's the obvious shortcut and it does work today — but it's a bad engineering bet, so it is deliberately not implemented:

• It belongs to the Copilot Language Server (editor plugins), not the CLI/SDK the runner drives — the shipping @github/copilot binary has zero references to it.
• Format churned twice in ~12 months (hosts.json → apps.json → auth.db), breaking downstream consumers both times.
• Encryption-at-rest already shipped once (CLS 1.505.0, AES-256-GCM) before an incident-driven rollback — today's plaintext is a temporary accident, not a contract.
• Reading another product's secret store is a credential-harvesting pattern worth avoiding regardless.

gh auth token is the documented, supported equivalent (copilot login --help lists "OAuth tokens from the GitHub CLI (gh) app"), and needs no special OAuth scope — Copilot entitlement is per-user seat.

Three defects fixed

1. provision-pool.sh failed on every run with default settings. Its default IMAGE_TAG used date -u +%Y%m%dT%H%M%SZ, but the ACA session-pool API lowercases image references while OCI tags are case-sensitive — so the image pushed as ...T1816Z-... and pool creation failed minutes later looking for ...t1816z-... (ImageManifestNotFound / MANIFEST_UNKNOWN). Default tag is now all-lowercase, and an uppercase override is rejected before any az call rather than after a multi-minute image build.

2. Error bodies were discarded. A non-2xx whose body carried no recognizable ACA message collapsed to the bare placeholder aca runner reported an error — actively misleading, since such a response may mean the runner was never reached. The raw body is now echoed (truncated). This immediately paid off during verification, surfacing the real cause:

   Error happened when allocating pod for identifier cond-…-implement-… in pool conductor-agent-pool

3. The example pinned an unavailable model.implement hard-coded model: gpt-4.1, which isn't available on all Copilot accounts and failed in-sandbox at session.create. It now inherits default_model (gpt-5-mini). Verified working: gpt-5-mini, claude-sonnet-4.5; not available: gpt-4.1, gpt-4o.

Test note worth reviewing

TestAcaCredentialPrecedence._clear_credential_env now also stubs the gh subprocess. Without it, every "no credential configured" assertion shells out and picks up the developer's real token — passing on a machine without gh, failing on one with it. I verified this is load-bearing: removing the stub makes test_raises_provider_error_when_neither_credential_configured fail with DID NOT RAISE.

Verification

• ✅ 4408 passed, 33 skipped (full suite)
• ✅ make check (ruff + ty) exit 0
• ✅ Live end-to-end against a real ACA pool with every credential env var unset — the gh fallback supplied the credential; the agent cloned the repo, wrote CONTRIBUTING.md, and completed in 73.14s for $0.0031:

  ✓ implement (73.14s, gpt-5-mini, 18769 in/516 out, $0.0031) → $end
  Workflow completed successfully
  

Docs

docs/providers/aca.md step 3 now leads with "nothing to do if you're signed in with gh", keeping the PAT as the documented escape hatch and preserving the trusted-use security posture (a gh token is broader than a Copilot-Requests PAT, and it does enter the sandbox). Added troubleshooting for the lowercase-tag failure, unavailable models, and 429s, plus two real setup blockers hit during the functional test: az login --tenant (plain az login can land on a disabled guest tenant, AADSTS500571) and uv tool install azure-cli --with pip (else az extension add fails with "No module named pip"). Also updated AGENTS.md, CHANGELOG.md, and DD4 in the design doc.

Related issues

Closes#284
Closes#336

• ClosesIdea: run agents inside Azure Container Apps sandboxes via a remote aca provider (Agent-in-Sandbox) #284 (aca provider epic) — this PR merges the full branch (29
  commits, E1–E11) into main, delivering the provider end-to-end: host
  transport, in-package runner, runner image, provisioning example, docs, and
  the credential resolution that completes DD4.

• Closesaca: make the Phase 2 credential gateway the default, configurable via workflow YAML (retire the plaintext stopgap as a silent default) #336 (make the credential gateway the default) — closed as
  superseded, not implemented. Two reasons, recorded in
  a comment on the issue:

  • Its premise no longer matches the codebase: it treats
    AcaCredentialGateway ("epic E8") as already shipped, but no such class
    exists on this branch or on main. It also cites DD4 as Proposed; DD4
    has since been settled as Accepted — "forward one narrowly-scoped
    credential; no modes" — which is the design this PR implements.
  • The residual concern (the credential is readable inside the sandbox) is
    real but is a known, documented carve-out of the trusted-use posture,
    not a regression: see docs/providers/aca.md#security. Keeping the
    credential entirely off the sandbox (a host-side broker/relay) remains
    tracked there as future work, and is worth a fresh issue written against
    the design as it actually shipped.

  Note for reviewers: this PR makes the default credential a gh OAuth
  token, which is broader than a Copilot Requests-only PAT. That trade is
  called out explicitly in the docs, which continue to recommend a scoped PAT
  wherever blast radius matters.