Connect a mailbox

Almost nothing in this job fails in the CLI. It fails in the Google Cloud console, twenty minutes earlier, in ways that only surface later: a client created as a Web application rather than a Desktop app returns redirect_uri_mismatch at the consent screen; an app left in Testing works perfectly and then dies with invalid_grant about seven days after sign-in, because Testing issues seven-day refresh tokens; the client secret is shown once, at creation, and a JSON that was not downloaded then cannot be recovered. Each of those looks like a bug in the tool when it arrives.

The second family of failures belongs to agents specifically. agent-gmail inbox add acme/gmail on a human terminal opens a browser and waits up to ten minutes for the redirect. An agent's shell does not live that long — Claude Code's Bash tool gives up at 120 seconds. The command tries to tell the two apart by itself and only waits when stdin and stdout are both terminals, so an agent usually gets the detached behaviour for free; but "usually" turns on whatever allocated the shell, and anything holding a pseudo terminal puts the ten-minute wait back. The two-step form (--start, then --finish) makes that choice yours rather than the environment's, and the waiting then always happens somewhere the agent is not.