Module runtime 

UI ↔ runtime contract.

Tracking: issue #274 of the workspace-refactor epic (#279).

The TUI today reaches deep into brain / coord / bus / rules internals. This module defines the read-only boundary it should reach through instead, so a future claudectl-tui crate (#275) can be extracted and iterated on without recompiling brain or the bus.

Why traits, why core-owned DTOs

Each view is a trait, not a concrete struct, so:

• The binary crate can hand the TUI a real implementation backed by SQLite / the engine / the bus DB. A future remote frontend can hand it an HTTP client. Tests hand it a fixture.
• Adding a method to a trait is a contract change reviewable in one PR; adding a method to a concrete struct ripples through every caller.

Each DTO (SessionSnapshot, LeaseSummary, …) is owned by core so the traits don’t drag brain::DecisionRecord / coord::Lease upward into the TUI’s dependency surface. Conversion happens once, in the wrapper.

What’s in scope here

Read-only views only. Side-effecting paths (terminate_session, inject_prompt, log_decision) deserve a separate Actions trait once the TUI’s write surface is mapped. Adding it speculatively now would violate the “only add methods existing call sites need” rule the epic committed to.

What’s NOT in scope

• The TUI doesn’t yet call through these traits — that’s #275.
• Brain’s review/scorecard surface — it’s heavier and worth its own trait once #275 stabilizes the basic shape.
• Pub/sub claim protocol — #283 builds on top of these traits, not the other way around.

Structs

AgentDirectoryEntry

DecisionSummary

A single past brain decision, projected for display.

HandoffSummary

HiveViewSnapshot

Snapshot of local hive state the overlay reads to render the Hive tab.

InterruptSummary

LeaseSummary

LogDecisionInput

What the TUI needs to record when the user resolves a brain suggestion. Carries the suggestion that was on screen at the time, plus what the user did and (optionally) why they overrode the brain.

MockRuntime

In-memory runtime backed by Vecs and interior-mutable counters. Used by tests in this crate to verify the trait shapes compile and roundtrip cleanly, and by the future claudectl-tui crate’s tests to render the TUI against fixtures without dragging in brain / coord / bus.

ObservationInput

What the TUI needs to record alongside a user action. Core-owned so the trait doesn’t drag brain::decisions::log_observation’s argument list upward into the TUI surface.

PendingSuggestion

One pending brain suggestion the user can accept or reject. Mirrors the binary’s brain::client::BrainSuggestion without exposing brain types.

ReviewItemSummary

One entry in the Brain Review queue — a decision worth showing the operator for canonical-marking review, with a reason and a priority score.

RoleBinding

Runtime

Single struct the binary builds at startup and hands to the TUI.

SessionSnapshot

One running Claude Code session, as observed by the runtime. Minimal projection of the binary-crate ClaudeSession; only fields the TUI renders.

Enums

BrainGateMode

Mirrors the binary’s brain::GateMode without depending on the brain crate. Persisted as the lowercased label.

DecisionScope

Whether a decision was about a session or about an orchestration task. Mirrors brain::decisions::DecisionType without depending on it.

MockAction

Recorded Actions calls. Tests use this to assert side-effect ordering without needing a real terminal or filesystem.

Traits

Actions

Side-effecting paths the TUI invokes when the user takes an action (terminating a session, sending a prompt, flipping the brain mode, recording an observation, marking a decision canonical for teaching).

BrainDriver

Stateful brain orchestration. Unlike the read-only views, this needs &mut per tick — the engine accumulates pending suggestions, cleans up after exited sessions, and applies user accept/reject decisions.

BrainReviewView

Read access to the Brain Review surface — the full decision log plus the review-queue projection. Separate trait from BrainView because:

BrainView

Read access to the brain’s decision history and current mode.

BusView

Read access to the agent-bus roster + role table. Disabled implementations (bus feature off in the binary) return empty vectors so the TUI can render the panel as “no bus” without conditional compilation.

CoordView

Read access to coordination state (leases, handoffs, interrupts). Backed today by the coord SQLite store; in tests, by a fixture.

HiveActions

Hive + relay surface the TUI needs to render the Skills and Hive panels.

Orchestrator

Tick the orchestration layer once per refresh: deliver pending mailbox messages, deliver pending coordination interrupts, and bookkeep stale rows in the underlying stores.

SessionSource

Read access to the live session roster.