# Mission Control agent guide
Terminal input, worker events and display projections. Cross-feature code belongs in layer folders (`state/`, `render/`, `controller/`, `input/`, `events/`); single-feature code in its owner (`sessions/`, `diff/`, `settings_editor/`, `prompt_editor/`, `transcript_cards/`). Shared standalone modules need not move into one consumer.
## Where to look
| Entry/events/send helpers | `../tui.rs`, `events.rs`, `events/delivery.rs` |
| Terminal restoration/graphics | `terminal.rs`, `terminal/` |
| Loop/input capture/pacing/reconciliation | `controller/`, `worker.rs` |
| Semantic input/state/drawing | `input/`, `state/`, `render/` |
| Session picker/prune/display hydration | `sessions/commands.rs`, `sessions/history.rs`, `sessions/history/` |
| Transcript store/cards/selection projection | `transcript.rs`, `transcript/`, `transcript_cards/`, `transcript_projection.rs` |
| Activity detail/read summaries | `activity.rs`, `activity/read_metadata.rs` |
| Changes refresh/comment saves | `diff.rs`, `diff/render.rs`, `diff/worker.rs` |
| Settings drafts/fields/geometry | `settings_editor.rs`, `settings_editor/{fields,render}.rs` |
| Shared modal shell/tabs/sizing | `modal_container.rs` |
| Usage/quota/side conversation | `session_usage.rs`, `usage.rs`, `controller/app/codex_quota.rs`, `controller/app/side.rs` |
| Child editor/runtime controls | `controller/app/subagent_prompt.rs`, `../subagents/control.rs` |
| Prompt editing/completion/selection | `prompt_editor.rs`, `prompt_editor/`, `single_line_field.rs`, `autocomplete.rs`, `selection.rs` |
| Prompt suggestions/image preview | `prompt_history.rs`, `images.rs` |
| Startup/release notes | `screens/primary_agent_startup.rs`, `release_notes.rs`, `render/transcript/welcome.rs` |
## Modal and layout contracts
- Use `modal_container.rs`: plain border, `theme.app()` background, name top-left, truthful Esc hint top-right, shortcuts bottom, shared Settings tabs. Default size 60% × 60%, clamped to 30–80%; diff comments explicitly 40% × 20%. Drawing and input share geometry.
- Activity Tree/Session Files/Summary are header modals (`Alt-1/2/3`), never rail tabs. Header row 1: right-aligned `[Alt+1-3]`, Activities/Files/Summary checkboxes, `• [Alt-A] Pin`; row 2: `[Shift-Tab] Cycle Tabs`. Open panels use `[•]`/active color; Pin shortcut always hotkey color.
- Unique `header_modals` follow opening order, stack top-to-bottom with equal heights/leftover rows from top; close expands remaining, reopen appends. Column is below header/above Prompt, one third of body, minimum 27 columns clamped to space, modal shell without surround.
- Pinned modals reserve Transcript column, capped at half body on narrow terminals. Pinning empty stack opens all three in shortcut order and sets `header_modals_opened_by_pin`; unpin closes that stack, otherwise restores overlays. Last close clears pin flags. Session switching preserves visibility/order/focus and both pin flags.
- Pinned panels hide on Changes without losing order/scroll; unpinned panels overlay either tab. Global `interface.tui.panel_layout` persists order/pin flags across restart; startup focuses Prompt without restoring scroll. Preferences never enter sessions/provider requests.
- Visibility differs from `focused_header_modal`. Letters/numbers/`/` and Prompt click focus editor without closing panels. Autocomplete-free pinned Tab cycles Prompt → Transcript → open modals → Prompt; unpinned panels stay outside Prompt/Transcript cycle.
- Header panels always show Alt Hide; pinned panels ignore Esc. Hints/borders follow actual focus; mouse close/scroll uses painted rectangles, not keyboard focus. Pinned Transcript stays interactive, other dialogs retain input ownership. Activity detail returns to tree; Summary visibility never controls generation. Side conversations exclude header modals/pinning.
- Transcript has titled border; `render::transcript_text_area_for_pane` supplies border-inset painting/hit-test/projection rectangle, including tiny panes. Changes replaces body but retains Prompt/rail; Git reads and saves stay in `diff/worker.rs`, storage in `../diff_review/`.
## Delivery and feature boundaries
- Primary queue is bounded at 1024 events; best-effort previews reserve 64 slots when capacity permits. Critical sends wait boundedly and report failure; synchronous delivery and worker-outcome reconciliation survive missing final wake events.
- Usage starts/snapshots persist before delivery; reconcile worker usage before folding completion. Totals outlive transcript/activity retention.
- Settings retains scoped changed-path drafts and requires restart. Model availability is Settings → Models; `/model` is cache-only even stale/missing. Explicit catalog refresh retains completion outside wake queue.
- Primary switching is blocked during runs. `controller/app/preferences.rs` writes local-only requested thinking through owned worker; resume/compaction preserve it without global changes, `/new` restores startup defaults.
- Side owns session/worker/events/steering/MCP but shares prompt execution/primary renderer. Hiding does not cancel; reset reconciles/joins before replacement and closes old MCP off-thread. Side history stays outside primary selection; only `/reset` works inside modal.
- `TranscriptEntries` owns IDs/timestamps/activity links/revisions. Move complete store during hydration; decode tool history at ingestion. Lazy width-specific indexes/cache reuse preserve final Markdown and width/theme/focus invalidation.
- Image references are untrusted; bounded preview worker reuses view-image path policy with separate decode limits. Drawing records visible rows, controller requests them. Kitty writes/cleanup belong to terminal owner, never transcript/copy; unsupported terminals/multiplexers stay text-only.
- Child drafts are separate: skill-only completion, no slash commands, literal `!`. Runtime controls own steering/cancellation. Completed children are read-only except pending-input recall; pending child steering blocks new primary run.
- Prompt history is local display only; filesystem work stays in startup/run workers. Record durable user submissions/steering, not auto-continuations, side or child prompts. Right Arrow accepts only painted suggestion at draft end; token completion wins.
- Terminal restoration covers errors/panics. `perf.rs` measures scroll apply-to-successful-draw, not input queue or physical display latency. Profiling stays with controller/render/transcript owners; compilation/Ratatui measurements do not prove terminal compatibility.
## Session picker and hydration
- `sessions/commands.rs` may read storage/use owning APIs; `sessions/history.rs` hydrates display only. Prune command stays independent of UI state.
- Picker reverses manager order and filters resolved cwd scope. Preserve preview file/event/message bounds; missing files yield empty, failures compact errors, partial scans remain partial. Previews never replace active state.
- `preserve_critical_tui_events` retains one finite 1024-event snapshot excluding previews; drain before live events, never requeue. Hydration retains timestamps/automatic-prompt provenance, groups reasoning, reconciles final text without duplicate chunks and bounds sanitized/redacted subagent replay size/depth.