Improve CodegenBackgroundAgent with Enhanced Auth and Troubleshooting

[codegen-sh]

Summary

This PR improves the CodegenBackgroundAgent specification based on real-world testing and usage. The agent was successfully tested and revealed several areas where the documentation could be enhanced for better user experience.

Changes Made

1. Enhanced Kickoff/Readiness Checks

• Added explicit CLI version check with telemetry handling
• Included organization listing and selection in authentication flow
• Added verification steps using codegen org --list

2. Improved Authentication Workflow

• Documented multi-organization handling
• Added CODEGEN_ORG_ID environment variable usage
• Provided guidance for avoiding interactive prompts in automation

3. Updated CLI Reference

• Replaced deprecated codegen create with codegen agent command
• Added real output examples (both formatted and JSON)
• Documented --json, --org-id, and --repo-id flags
• Included environment variable setup

4. Comprehensive Troubleshooting Section

New troubleshooting guidance covering:

• "Not authenticated" errors with step-by-step resolution
• Multiple organization handling
• TTY/non-TTY environment issues
• CLI version checking and updates
• Agent run creation failures

5. Enhanced Failure & Escalation

• Expanded authentication failure handling
• Added organization selection issue guidance
• Included interactive prompt failure scenarios
• Better error recovery paths

Testing

✅ Successfully created test agent run (ID: 105016)
✅ Verified authentication flow with multi-org setup
✅ Tested organization switching commands
✅ Confirmed CLI output formats

Impact

These improvements make the CodegenBackgroundAgent:

• More robust for both interactive use and automation
• Easier to troubleshoot when issues arise
• Better documented for new users
• Production-ready with clear error recovery paths

Request: @jaruesink

---

💻 View my work • 👤 Initiated by @jaruesink • About Codegen
⛔ Remove Codegen from PR • 🚫 Ban action checks

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codegen-bot/improve-codegen-background-agent-1759290765

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}