Description

Global feature flags need to be available before command construction, but a network lookup cannot delay every invocation. This PR adds an immutable global snapshot backed by a stale-while-revalidate cache.

The provisional unauthenticated Twirp contract is enabled only through GH_GLOBAL_FEATURE_FLAG_SERVER_URL. Startup reads the cache synchronously, then uses a detached internal worker to refresh values for a later invocation.

The worker runs before configuration, telemetry, update checks, and command construction. Failed refreshes have a one-minute cooldown, while cache writes remain atomic and endpoint-isolated.

How did you test this change?

Given I built bin/gh and configured a local server with a 1.5 second response delay

When I ran bin/gh --help with GH_GLOBAL_FEATURE_FLAG_SERVER_URL set

Then the command returned in 0.253 seconds and the detached worker populated the cache afterwards

Given the local server returned HTTP 503

When I ran bin/gh --help three times

Then I saw one detached request because the remaining invocations observed the cooldown

I exercised both scenarios with:

$ python3 /tmp/gh-global-flags-smoke.py
success: enabled=0.253s normalized_cache=true
failure: three invocations produced one detached request

Key points

• A goroutine cannot reliably warm the cache after a short-lived gh process exits, so refresh uses a detached subprocess.
• Flags may take effect on the next invocation. They are rollout hints, not an authorisation mechanism.
• No production CAFE endpoint is assumed. Without GH_GLOBAL_FEATURE_FLAG_SERVER_URL, startup stays offline with every flag disabled.
• This does not implement user-scoped flags or use GitHub accounts, tokens, repository context, or host routing.

Notes for reviewers

I would start with internal/globalflags, which owns the provisional contract, cache, validation, and refresh state. internal/ghcmd/global_flags.go then shows the startup policy and isolated worker lifecycle.

Authorship and follow-up

Who wrote this:

• A human wrote it.
• An agent wrote it under close human direction.
• An agent wrote it independently, and no human has guided the implementation beyond the initial prompt.

Who answers review comments:

• @username will read and reply directly. Name the account.
• An agent will draft replies and @williammartin will read them before they are posted.
• Nobody has explicitly committed to replying.