🧞 Genie Session & Wish Improvements

[vasconceloscezar]

Summary

Fix critical Genie bugs and improve the wish creation experience. Multiple feedbacks reported session failures, branch confusion, and inconsistent wish creation.

Problems Identified

1. Database Constraint Violation on Consecutive Sessions (BLOCKING)

Current: Cannot create Genie sessions consecutively. Second attempt fails.
Error:

Failed to start Master Genie: DatabaseError: error returned from database:
(code: 2067) UNIQUE constraint failed: forge_agents.project_id, forge_agents.agent_type

Root Cause Hypothesis:

• Previous sessions not cleaned up (orphaned records)
• Missing upsert logic when creating sessions
• UNIQUE constraint without proper cleanup

Solution:

• Implement proper session cleanup on close
• Use upsert instead of insert for session creation
• Add session recovery for orphaned records

2. Genie Creates Tasks on Wrong Branch

Current: Wishes start tasks on dev branch instead of current branch.
Impact: Users create feature branches but Genie ignores them.

Additional issue: Aborting tasks on non-existent branch corrupted database records.

Solution:

• Respect current project branch setting
• Use branch from task context, not hardcoded dev
• Handle missing branch gracefully without corruption

3. Wish Creation Inconsistency

Current: Asking Genie to create wishes based on a plan is unreliable.
Impact: Sometimes hallucinates, "wish" vs "tasks" terminology confusion.

Solution:

• Clearer wish creation prompts/templates
• Consistent terminology in UI and agent instructions
• Better error handling when wish creation fails
• Validation before creating wish tasks

4. First-Run Experience Missing

Current: First Genie interaction has no guidance.
Impact: Users don't know what to do, no "wow factor".

Solution:

• Pre-populated example on first run (e.g., @bug_fixes template)
• Popover explaining the concept
• Quick-start suggestions
• "Try this" prompt to demonstrate capability

5. Profile Cache Race Condition (Related)

Note: #276 documents a related issue where agents don't appear on fresh install due to cache timing.

Acceptance Criteria

• Can create multiple Genie sessions consecutively without error
• Wishes respect current branch, not hardcoded dev
• Wish creation is reliable and consistent
• First-time users see helpful onboarding
• No database corruption on edge cases

Related Issues

• Profile cache race condition: agents not shown on fresh install #276 (Profile cache race condition)

Technical Notes

Affected Components:

• forge_agents table constraints
• Session creation/cleanup logic
• Wish creation flow
• Branch resolution in task creation

Team Feedback Sources

• Feedback 1: DB constraint violation (blocking)
• Feedback 4: Wrong branch, first-run experience
• Feedback 5: Wish creation inconsistency

Priority

🔴 P0 - Critical (blocking bug + 3/6 feedbacks)