# Controller agent guide
## Where to look
| Main loop and app ownership | `app/mod.rs` |
| Event application handoff | `drain.rs` (`DrainResult`, `DrainOutcome`) |
| Terminal capture and flush fence | `input_bridge.rs` |
| Redraw, cursor timers, scroll coalescing | `pacing.rs` |
| Actions and display effects | `app/actions.rs`, `app/reducer.rs`, `app/display_reducer.rs` |
| Readiness and initial prompt | `app/startup.rs` |
| Submission and run lifecycle | `app/submit.rs`, `app/workers.rs` |
| Auth, theme, model catalog | `app/auth.rs`, `app/theme.rs`, `app/catalog.rs` |
| Compaction, rewind, export | `app/compaction.rs`, `app/rewind.rs`, `app/export.rs` |
| Scoped settings and global fast mode | `app/settings_persistence.rs`, `app/fast_mode_persistence.rs` |
| Session listing/pruning | `app/session_maintenance.rs` |
| Idle restart and quota refresh | `app/updates.rs`, `app/codex_quota.rs` |
## Local contracts
- Drain at most 128 events or 2ms per pass. Preserve `DrainResult`, input-to-paint barriers, and redraw decisions; input feedback must not wait behind unbounded backlog.
- Normal-loop joins check `is_finished()` first. Match completion identities before replacing workers; queued completion markers can outlive their worker.
- Session switching retains one finite event snapshot and drains it before live events under the same budget, never back into the channel. Switch results must match the pending request and session generation; rewind, export, and model selection also validate captured session context.
- A queued initial prompt requires critical readiness, a painted frame, and the input flush fence. Decorative loads must not delay readiness.
- Keep action/context values data-only; display commands belong in the display reducer.
- Settings and session-maintenance workers retain join results independently of wake delivery. Footer branch refresh also retains a completion mailbox and the worker until finished.
- Auth reads/removal share one worker. Apply reads only to matching modal state; removal blocks prompt admission. Shutdown may detach reads but must join removal.
- Theme picker reopen reuses its in-flight catalog worker; allow one save worker. Match request ids and theme revisions, retain failed deliveries, bound shutdown catalog waits to 100ms each, and join persistence.
- Fast-mode saves are global. Update memory only after persistence confirmation; retain delivery/join failures and block retries after restart-required failure.
- Settings saves retain prior selections until success. Preserve scope checks and model-selection exclusion; refresh can fail after disk persistence succeeds, requiring restart.
- Session maintenance checks captured generation and never reopens a closed picker. Separate pruning from prompts/switches; retain the prune report if subsequent listing fails.
- Modal scope changes preserve global/project separation and refresh disabled settings; bound and sanitize status text.
- Update checks retain one timeout-bounded worker result outside the event queue. `/update` returns an idle restart request, not Cargo execution in the loop; restart data must not retain a session lease.
- Codex quota refresh owns one join-result worker, including stored-auth checks. HTTP is activity-gated at five minutes and `/usage` shares pending work. Match the final request's account, not token revisions; account changes, logout, invalidation, and failure must clear stale indicators.