🎯 What Is Ultraplan?
Remote planning mode. /ultraplan or embedding 'ultraplan' in a prompt spawns a full CCR session on the most powerful model (Opus) with 30-minute window. Local terminal stays free.
Phase 1: Trigger Detection
Keyword scanner finds 'ultraplan' in freeform input or slash command routes it.
Phase 2: CCR Session Launch
teleportToRemote() creates remote session, uploads git bundle, returns session ID.
Phase 3: Long-Poll
pollForApprovedExitPlanMode() polls event stream every 3s for up to 30 min.
Phase 4: Plan Delivery
Plan lands locally via UltraplanChoiceDialog or stays in CCR.
🔍 Keyword Smart Disambiguation
The word 'ultraplan' fires from freeform text unless context makes clear it's not a directive. Filtered OUT: slash-command input, inside paired delimiters (backticks, quotes, tags), path/identifier context (preceded by / or -), followed by ? (questions), followed by . + word char.
💡 Safety Gate
Detection runs against pre-expansion input to prevent pasted content from accidentally triggering ultraplan.
🔄 Phase State Machine
running → needs_input
Quiet idle waiting for user input in browser.
running → plan_ready
ExitPlanMode tool_use seen in event stream.
plan_ready → approved
User approves in CCR browser. Remote execution.
plan_ready → teleport
User clicks 'back to terminal'. Sentinel __ULTRAPLAN_TELEPORT_LOCAL__.
📦 Plan Delivery Paths
Path A — Remote Execution
User approves in CCR browser. Local CLI marks task completed, enqueues notification.
Path B — Teleport
User clicks 'back to terminal'. Browser sends is_error=true tool_result with sentinel. Local CLI shows UltraplanChoiceDialog.
⚙️ Polling Engine
Cursor-based pagination fetches up to 50 pages per tick. ExitPlanModeScanner classifies events as approved / teleport / rejected / pending / terminated. Tolerates up to 5 consecutive network failures.
💡 Session Survival
Sessions survive --resume via sidecar metadata files. Model selection via GrowthBook feature flag, not hardcoded.
🔑 Key Design Decisions
💡 Detached Pattern
Returns user-facing message immediately. All async work runs in void closure. ultraplanLaunching flag set synchronously before any async call to close double-launch race window.