[vscheuber]

Phase 3 follow-up: realm picker + pickable-option help annotations

Completes the last two Phase 3 items from the interactive-commands plan (builds on #784).

Realm picker

After a successful login, a command whose realm argument was left at its default offers a dropdown of the target system's realms — but only when it makes sense to:

• prompting is allowed (canPrompt() — never in FRODO_TEST/CI or non-TTY runs),
• the command declares a [realm] positional argument,
• the user did not name a realm (positional or FRODO_REALM), and
• the target system reports more than one realm (a single-realm tenant has no choice to offer).

Every other path is a no-op, so non-interactive behavior is byte-identical to before. Escape declines the offer and keeps the deployment-type default (unlike entity pickers, there is no "wrong" continuation to protect — the default is a valid choice). A failed realm listing is swallowed and the default kept.

The two subtle parts:

• Provenance is captured pre-auth. frodo-lib maps the __default__realm__ sentinel to the deployment type's realm (alpha / /) during _getTokens, so after auth a user choice and a mapped default are indistinguishable. noteRealmProvenance() therefore runs in the resolution pass before auth; the picker consults it post-auth.
• One fetch for the realms endpoint. The picker and frodo realm list now share a memoized readRealmsCached() in RealmOps — without it, the picker's extra read broke Polly's order-matched replay in existing e2e recordings (they hold one entry for the endpoint) and doubled latency.

Wiring is global: the getTokens wrapper fires the pick for every command; commands that bypass the resolution pass (login/conn stub actions) naturally never see it.

Help annotation for pickable options

FrodoStubHelp now renders (pick from <kind>) on options with a registered entity picker, e.g.:

-i, --secret-id <secret-id>  Secret id. If specified, -a is ignored. (pick from secret)

so interactive users can see which options will offer a live dropdown before running the command. The 25 affected client_cli help snapshots are updated (annotation-only diffs, verified).

Layering note

The picker's post-auth hook needs the active command, but ops/ importing
cli/ResolveInteractiveInputs directly would drag the resolution pass's
graph (the frodo-lib-importing interactive prompts) into tests that mock
frodo-lib wholesale. The active-command registry therefore lives in its own
zero-import module (ActiveActionCommandState, same split as
PromptGateState), and the picker machinery is lazy-imported in the
getTokens wrapper behind canPrompt() — non-interactive sessions never
load it.

Tests

• RealmPickers.test.ts (new): pins the non-interactive preservation contract — under FRODO_TEST=1, without a realm argument, with a user-specified realm, or without provenance noted, resolveRealmPick is a strict no-op (no read, no write).
• Full suite green locally against the fresh build; all 362 client_cli suites pass (snapshot updates applied); PTY-verified against the rebuilt binary (picker renders for the 2-realm mock tenant; default accepted and explicit pick both complete cleanly).

🤖 Generated with Claude Code