feat(cli): bgagent change-password command + force-rotate on first login

[isadeks]

Problem

The current admin onboarding flow (bgagent admin invite-user <email>) creates a Cognito user with a permanent password that the admin generates and shares with the teammate via Slack/email. Two UX gaps fall out of that:

1. No way for a teammate to rotate their password. They keep using the admin-generated string forever unless they go through Cognito's console manually. The CLI has no bgagent change-password command.
2. The admin's terminal scrollback / Slack message stays canonical. The shared password is the actual login credential indefinitely. Standard secure pattern is a temporary admin-generated password that the teammate must replace on first login — that one-line message stops being a credential after the teammate logs in once.

Acceptance criteria

Part 1 — change-password command

• New bgagent change-password command. Interactive: prompts for current password + new password (twice for confirmation).
• Calls Cognito's ChangePasswordCommand against the user's current session token.
• Cognito enforces password policy server-side and returns a structured error; surface it cleanly.
• Works for any user with a valid bgagent login session.
• Tests: success, wrong current password, weak new password, no session.

Part 2 — force-rotate on first login

• Flip bgagent admin invite-user to set a temporary password (drop the Permanent: true on AdminSetUserPassword).
• Handle the NEW_PASSWORD_REQUIRED challenge in bgagent login: when Cognito returns it, prompt the teammate for a new password, call RespondToAuthChallenge, persist the resulting tokens.
• Update LINEAR_SETUP_GUIDE.md and USER_GUIDE.md teammate-onboarding sections to reflect the new flow ("you'll be prompted to set a permanent password on first login").

Out of scope (future)

• Forgot-password (ForgotPassword + ConfirmForgotPassword) — needs Cognito email delivery, which means SES wiring. Park as a separate followup.
• MFA enrollment.
• Admin-side password rotation (admin reset-password <email>) — distinct from a user changing their own password.

Files

• cli/src/commands/change-password.ts (new)
• cli/src/commands/admin.ts — drop Permanent: true
• cli/src/auth.ts — handle NEW_PASSWORD_REQUIRED challenge in login
• cli/src/bin/bgagent.ts — register change-password
• cli/test/commands/change-password.test.ts (new)
• cli/test/commands/admin.test.ts — update for temp password
• cli/test/auth.test.ts — challenge-flow coverage
• docs/guides/LINEAR_SETUP_GUIDE.md + docs/guides/USER_GUIDE.md — teammate-flow updates
• Mirrors regenerated via docs/scripts/sync-starlight.mjs

Verification

• bgagent change-password rotates an existing user's password end-to-end.
• New admin invite-user flow: admin runs invite → teammate receives bundle + temp password → first bgagent login prompts them to set a permanent password → second bgagent login succeeds with the new password.

[krokoko]

Relevance check (Jun 2026)

Reviewed the current CLI against this issue's acceptance criteria. The issue is still relevant — recent operator/admin commands improve onboarding and day-2 ops, but they do not implement the user-facing password flows described here.

What landed since this issue was filed

The bgagent admin command group (invite-user, list-users, delete-user, reset-password) and bgagent ops (stuck-tasks, concurrency) cover stack-admin operations using operator IAM credentials. admin reset-password can set a new permanent password for a user, which is helpful for admins but was explicitly scoped out here as distinct from self-service rotation.

Gaps that remain open

Criterion	Status
bgagent change-password (ChangePasswordCommand against the user's session)	Not implemented
invite-user drops Permanent: true / uses temp password only	Opposite today — adminInviteUser calls adminSetPermanentPassword with Permanent: true
login handles NEW_PASSWORD_REQUIRED via RespondToAuthChallenge	Not implemented — auth.ts only handles a successful AuthenticationResult
Docs (USER_GUIDE.md, LINEAR_SETUP_GUIDE.md) updated for first-login password set	Opposite today — docs state permanent password, no forced change on first login
Tests (change-password, challenge flow, temp invite)	Missing

Design tension worth noting

The current invite flow was intentionally built to skip Cognito's FORCE_CHANGE_PASSWORD challenge: cognito-admin.ts documents adminSetPermanentPassword as "skips FORCE_CHANGE_PASSWORD on first login," and admin invite-user prints "Set permanent password (no first-login change required)." Implementing Part 2 of this issue would be a deliberate behavioral change to that flow, not just filling in a missing command.

Minor issue hygiene

The file list in the issue body is slightly stale: Cognito admin logic now lives primarily in cli/src/cognito-admin.ts (with cli/src/commands/admin.ts as the command wiring). Tests are split across cli/test/commands/admin.test.ts and cli/test/commands/cognito-admin.test.ts.

Suggested next step

If we still want the security posture described here (temp admin password → user sets permanent password on first login + ongoing self-service change-password), this issue remains the right tracking item. Worth confirming at implementation time whether we want to flip the current permanent-password invite design or offer both modes.

[scottschreckengaust]

@scottschreckengaust (agent:w6) working on it — #238 — branch feat/issue-238-change-password

[scottschreckengaust]

🤖 @scottschreckengaust (agent:w6) — signing out, over and out.

DRAFT: PR #680 (draft); body has an unformatted Closes #238 (closingIssuesReferences → [238], auto-closes on merge). Self-review complete (approve-with-nits, zero code blocking; fixed the previously-backticked Closes line). In orchestrator's review pipeline.