Stop concurrent basecamp processes from losing a credential, and let an agent authenticate

.surface

@@ -1955,6 +1955,7 @@ FLAG basecamp auth --verbose type=count
 FLAG basecamp auth login --account type=string
 FLAG basecamp auth login --agent type=bool
 FLAG basecamp auth login --cache-dir type=string
+FLAG basecamp auth login --client-id type=string
 FLAG basecamp auth login --count type=bool
 FLAG basecamp auth login --device-code type=bool
 FLAG basecamp auth login --expect-identity type=string
@@ -1980,6 +1981,7 @@ FLAG basecamp auth login --stats type=bool
 FLAG basecamp auth login --styled type=bool
 FLAG basecamp auth login --todolist type=string
 FLAG basecamp auth login --verbose type=count
+FLAG basecamp auth login --with-client-credentials type=bool
 FLAG basecamp auth login --with-token type=bool
 FLAG basecamp auth logout --account type=string
 FLAG basecamp auth logout --agent type=bool
@@ -10775,6 +10777,7 @@ FLAG basecamp lineup update --verbose type=count
 FLAG basecamp login --account type=string
 FLAG basecamp login --agent type=bool
 FLAG basecamp login --cache-dir type=string
+FLAG basecamp login --client-id type=string
 FLAG basecamp login --count type=bool
 FLAG basecamp login --device-code type=bool
 FLAG basecamp login --expect-identity type=string
@@ -10800,6 +10803,7 @@ FLAG basecamp login --stats type=bool
 FLAG basecamp login --styled type=bool
 FLAG basecamp login --todolist type=string
 FLAG basecamp login --verbose type=count
+FLAG basecamp login --with-client-credentials type=bool
 FLAG basecamp login --with-token type=bool
 FLAG basecamp logout --account type=string
 FLAG basecamp logout --agent type=bool

README.md

@@ -222,6 +222,26 @@ an envelope with the profile, account, identity and person, `oauth_type`,
 `null` when it reports none). A token has no refresh token, so near a reported
 expiry the CLI refuses it and asks for a fresh import.
 
+### Agents
+
+A Basecamp agent is a principal with no person behind it, so it has no browser
+to sign in with and is granted no refresh token. It authenticates with the
+OAuth `client_credentials` grant instead: its client id and secret mint a
+short-lived self-token, and the CLI mints another whenever that one nears
+expiry. The client secret is read from stdin (never an argument) and stored
+with the token it mints — in the OS keyring where one is available — because
+the client, not a refresh token, is what survives an expiry:
+
+```bash
+op read "op://Vault/Item/credential" | basecamp auth login --with-client-credentials --client-id <id> -P agent --account 999
+```
+
+The login mints once, which is what proves the client id and secret: a refused
+mint stores nothing. `--account` is required when the profile does not exist
+yet. `basecamp auth logout` forgets the credential; there is no useful
+revocation, since the same client would mint another — rotate the client
+secret in Basecamp to end an agent's access.
+
 ### Multiple Identities
 
 Use named profiles when the same machine or agent gateway needs more than one Basecamp identity. Each profile has its own stored OAuth credentials and can be selected per command:

e2e/auth.bats

@@ -115,6 +115,41 @@ load test_helper
   assert_json_value '.code' 'usage'
 }
 
+@test "basecamp auth login --help shows the agent client-credentials flags" {
+  run basecamp auth login --help
+  assert_success
+  assert_output_contains "--with-client-credentials"
+  assert_output_contains "--client-id"
+  assert_output_contains "no refresh token"
+}
+
+@test "basecamp auth login --with-client-credentials requires a client id" {
+  run basecamp auth login --with-client-credentials -P agent </dev/null
+  assert_failure
+  assert_json_value '.error' '--with-client-credentials needs the agent'"'"'s OAuth client id'
+  assert_json_value '.code' 'usage'
+}
+
+@test "basecamp auth login --with-client-credentials requires a profile" {
+  run env -u BASECAMP_PROFILE basecamp auth login --with-client-credentials --client-id abc </dev/null
+  assert_failure
+  assert_json_value '.error' '--with-client-credentials stores the credential under a named profile'
+  assert_json_value '.code' 'usage'
+}
+
+@test "basecamp auth login rejects --client-id on its own" {
+  run basecamp auth login --client-id abc </dev/null
+  assert_failure
+  assert_json_value '.error' '--client-id only applies to an agent login'
+  assert_json_value '.code' 'usage'
+}
+
+@test "basecamp auth login --with-client-credentials rejects --with-token" {
+  run basecamp auth login --with-client-credentials --with-token </dev/null
+  assert_failure
+  assert_output_contains "with-client-credentials"
+}
+
 @test "basecamp auth login --with-token rejects --device-code" {
   run basecamp auth login --with-token --device-code </dev/null
   assert_failure

install.md

@@ -199,6 +199,19 @@ basecamp search "meeting" --json
 
 ## Troubleshooting
 
+**Check what you are fixing first.** `basecamp auth status --json` reports
+`oauth_type`, and `agent` means the profile is a Basecamp agent: a principal
+with no person behind it, which authenticates with its OAuth client rather than
+a sign-in. None of the logins below apply to one — they would store a person's
+credential over it — and `auth logout` would throw away the client credentials
+it needs to recover. An agent re-authenticates with its own login, which
+replaces the credential in place. When `oauth_type` is absent, run whatever
+the status output's own hint names rather than choosing from the list below:
+
+```bash
+op read "op://<vault>/<item>/credential" | basecamp auth login --with-client-credentials --client-id <id> -P <profile> --account <id>
+```
+
 **Not authenticated:**
 ```bash
 basecamp auth login