CLI Login

A login is the one step only the user can take: he opens a link in his own browser and signs in with his password manager or passkey. The agent's part is to start a login that needs no terminal, put the link in front of him, and confirm afterwards that the session exists. No password and no token passes through the agent, and the user's active account never changes unless he asks.

Why the obvious ways fail

• A login that waits for pasted input hangs. gcloud auth login --no-launch-browser and --no-browser read a code from the terminal; a dispatched agent has none.
• A background task can die before the click. The host may stop an agent's background task when the turn ends, and the localhost listener that would receive the browser's answer dies with it.
• A plain login switches the active account. gcloud auth login activates the new account for every session on the machine, so it asks for a signature; --no-activate adds the account without switching.

Procedure (gcloud)

1. Start it detached. gaia login start gcloud --account <email> runs gcloud auth login <email> --no-activate in its own session and prints JSON with login_id, state: pending and url. It runs free: it cannot switch the account.
   • Already held. When gcloud already stores a credential for the account it re-uses it and prints no link; the start exits 0 with state: already_signed_in and no url, and gaia login status reports the same. Nothing to click: continue the task.
   • Expired or stale. If commands with --account <email> still fail after already_signed_in, renew with gaia login start gcloud --account <email> --force. It runs gcloud auth login <email> --no-activate --force, returns a fresh link, and is free for the same reason: it never activates the account.
2. Close the turn on the link. Close NEEDS_INPUT. Put the url in your conclusion for the orchestrator, which hands it to the user as a link with one line: open it, sign in, and reply when done. Say it must be opened in a browser profile, or an incognito window, that holds only the target account: each link allows exactly one sign-in attempt, because gcloud stops listening after the browser's first answer. Record the login_id in key_outputs.
3. On resume, confirm. gaia login status <login_id> reports pending, complete or failed. complete means gcloud exited cleanly and gcloud auth list shows the account. Then continue the task with --account <email> on the commands that need it.
4. Wrong account. If he signs in with another account, gcloud refuses it with "the received credentials were for account [...]" and status goes to failed. The link is spent; recover with a fresh gaia login start gcloud --account <email> --force.
5. On failed or a refused start, report it. A start that reports the copy-code flow means gcloud found no browser it could launch; that machine needs the live interop check, not a retry.

The link redirects to http://localhost:<port>. Windows forwards localhost into WSL, so the browser on Windows reaches the listener whether or not WSL interop is enabled. The login stops on its own after 10 minutes.

Other CLIs

Not wired yet. gh auth login makes the new account the active one, so adding a GitHub account goes through an isolated gh config directory (next slice). gws and Microsoft 365 follow the same start, link, confirm cycle once their launchers exist.

Anti-patterns

• Running the login in a background Bash task and waiting. The host can stop it before the user clicks; use gaia login start.
• Reading ~/.config/gcloud to check the session. That path is read-refused; gaia login status and gcloud auth list are the checks.
• Activating the account to make later commands shorter. Pass --account per command instead.