claudectl-core 0.57.0

//! 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.

use serde::{Deserialize, Serialize};
use std::sync::Arc;

// ============================================================================
// Sessions
// ============================================================================

/// One running Claude Code session, as observed by the runtime. Minimal
/// projection of the binary-crate `ClaudeSession`; only fields the TUI
/// renders.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SessionSnapshot {
    pub session_id: String,
    pub pid: u32,
    pub cwd: String,
    pub project_name: String,
    pub status: String,
    pub cost_usd: f64,
    pub context_tokens: u64,
    pub context_max: u64,
    pub last_message_ts: u64,
}

/// Read access to the live session roster.
pub trait SessionSource: Send + Sync {
    /// Snapshot of every running Claude Code session. Order is the
    /// implementor's choice; the TUI sorts again client-side.
    fn list(&self) -> Vec<SessionSnapshot>;

    /// Fetch a specific session by its ID. `None` when the session has
    /// exited or never existed.
    fn detail(&self, session_id: &str) -> Option<SessionSnapshot> {
        self.list().into_iter().find(|s| s.session_id == session_id)
    }
}

// ============================================================================
// Brain
// ============================================================================

/// Mirrors the binary's `brain::GateMode` without depending on the brain
/// crate. Persisted as the lowercased label.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum BrainGateMode {
    On,
    Off,
    Auto,
}

impl BrainGateMode {
    /// Canonical lowercase label — the form persisted to
    /// `~/.claudectl/brain/gate-mode` and emitted by the TUI status messages.
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::On => "on",
            Self::Off => "off",
            Self::Auto => "auto",
        }
    }
}

impl std::fmt::Display for BrainGateMode {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

/// A single past brain decision, projected for display.
///
/// The first six fields are the common shape used by `BrainView::recent_decisions`.
/// The remaining fields support the Brain Review surface (`BrainReviewView`); they
/// are `Option`-wrapped + `#[serde(default)]` so older `BrainView` callers can
/// keep treating them as opaque.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DecisionSummary {
    pub id: String,
    pub timestamp: String,
    pub action: String,
    pub confidence: Option<f64>,
    pub project: Option<String>,
    pub tool: Option<String>,
    /// PID of the session this decision belongs to. Used by counterfactual
    /// analysis to pair decisions with their subsequent outcome from the
    /// same session.
    #[serde(default)]
    pub pid: u32,

    /// Tool input string when the decision was about a specific command.
    #[serde(default)]
    pub command: Option<String>,
    /// Brain's free-form rationale for the suggestion.
    #[serde(default)]
    pub reasoning: Option<String>,
    /// What the user did with the suggestion — `"accept"`, `"reject"`,
    /// `"deny_rule_override"`, etc.
    #[serde(default)]
    pub user_action: Option<String>,
    /// Why the user overrode the brain (if applicable).
    #[serde(default)]
    pub override_reason: Option<String>,
    /// Wall-clock latency of the brain decision in milliseconds.
    #[serde(default)]
    pub brain_decision_ms: Option<u64>,
    /// Whether the operator has marked this decision as canonical (teaching
    /// material). `None` for records written before the field existed.
    #[serde(default)]
    pub canonical: Option<bool>,
    /// Cache hit flag — served from the few-shot store without an LLM call.
    /// `None` before instrumentation.
    #[serde(default)]
    pub cache_hit: Option<bool>,
    /// Cost in USD when this decision was made (context snapshot).
    #[serde(default)]
    pub cost_usd: Option<f64>,
    /// Model that produced the suggestion.
    #[serde(default)]
    pub model: Option<String>,
    /// Resolved outcome category, when known. `"success" | "error" |
    /// "test_failed" | "skipped"` etc. Mirrors the variants of the binary's
    /// `brain::decisions::DecisionOutcome` enum, flattened to a string so
    /// the contract doesn't pull the enum upward.
    #[serde(default)]
    pub outcome_kind: Option<String>,
    /// Free-form detail for failure outcomes (the failing command for
    /// `test_failed`, the error message for `error`).
    #[serde(default)]
    pub outcome_detail: Option<String>,
    /// Epoch seconds when the brain suggestion was first surfaced. Used by
    /// time-to-correct analysis. `None` for records pre-instrumentation or
    /// passive observations.
    #[serde(default)]
    pub suggested_at: Option<u64>,
    /// Epoch seconds when the user acted on the suggestion. `None` for
    /// passive observations or records still in flight.
    #[serde(default)]
    pub resolved_at: Option<u64>,
}

impl DecisionSummary {
    /// Whether the user agreed with the brain (or the call was auto-executed).
    /// Mirrors `brain::decisions::DecisionRecord::is_positive`.
    pub fn is_positive(&self) -> bool {
        matches!(
            self.user_action.as_deref(),
            Some("accept" | "auto" | "user_approve" | "rule_approve")
        )
    }

    /// Whether the user disagreed with the brain. Mirrors
    /// `brain::decisions::DecisionRecord::is_negative`.
    pub fn is_negative(&self) -> bool {
        matches!(
            self.user_action.as_deref(),
            Some("reject" | "deny_rule_override" | "rule_deny" | "conflict_deny")
        )
    }
}

/// Read access to the brain's decision history and current mode.
pub trait BrainView: Send + Sync {
    fn gate_mode(&self) -> BrainGateMode;

    /// Most recent `n` decisions, newest first.
    fn recent_decisions(&self, n: usize) -> Vec<DecisionSummary>;

    /// Total count of brain decisions on disk. Drives the "decisions: N"
    /// status line.
    fn decision_count(&self) -> usize;
}

/// One entry in the Brain Review queue — a decision worth showing the operator
/// for canonical-marking review, with a reason and a priority score.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ReviewItemSummary {
    pub decision: DecisionSummary,
    /// Free-form rationale for why this decision was queued for review.
    pub reason: String,
    /// Priority score (higher = more important to review first).
    pub score: f64,
}

/// Read access to the Brain Review surface — the full decision log plus the
/// review-queue projection. Separate trait from `BrainView` because:
///
/// - The Brain Review screen is the only TUI consumer; the dashboard's status
///   bar only needs `BrainView::recent_decisions(n)`.
/// - `all_decisions()` returns the whole log (can be thousands of records);
///   it's a heavier surface than the lightweight `BrainView` methods and
///   worth gating behind its own trait so callers don't accidentally invoke it.
pub trait BrainReviewView: Send + Sync {
    /// Every decision on disk, newest first. Used by the Brain Review screen
    /// to render the full history list.
    fn all_decisions(&self) -> Vec<DecisionSummary>;

    /// Priority-ordered review queue. Built from `all_decisions()` plus the
    /// brain's queue-building heuristics (counterfactual hits, Critical-tier
    /// safety cases, high-confidence misses).
    fn review_queue(&self) -> Vec<ReviewItemSummary>;
}

// ============================================================================
// Coordination layer
// ============================================================================

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LeaseSummary {
    pub id: String,
    pub owner_session_id: String,
    pub resource_kind: String,
    pub resource_value: String,
    pub mode: String,
    pub acquired_at: String,
    /// ISO timestamp when the lease expires. `None` for leases held without
    /// an explicit deadline.
    #[serde(default)]
    pub expires_at: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HandoffSummary {
    pub id: String,
    pub from_session_id: String,
    pub to_session_id: Option<String>,
    pub task_id: String,
    pub summary: String,
    pub priority: String,
    pub created_at: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InterruptSummary {
    pub id: String,
    pub interrupt_type: String,
    pub priority: String,
    pub target_session_id: String,
    pub reason: String,
    pub created_at: String,
}

/// A supervisor task lifecycle, projected for the TUI. One row per task in the
/// coord `tasks` table. `state` is the wire label (`TaskState::as_str`), kept as
/// a string so the contract doesn't drag the coord state enum upward.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TaskSummary {
    pub id: String,
    pub name: String,
    pub state: String,
    pub role: Option<String>,
    /// Number of recorded attempts so far.
    pub attempts: u32,
    pub max_retries: u32,
    /// Session id of the most recent attempt, when one has run.
    pub last_session_id: Option<String>,
    /// Most recent verifier verdict (e.g. "PASS"/"FAIL"), or `None` if no
    /// verifier has run for this task yet.
    #[serde(default)]
    pub last_verdict: Option<String>,
    /// Total cost in USD across all attempts.
    #[serde(default)]
    pub cost_usd: f64,
    pub created_at: String,
    pub updated_at: String,
}

/// Read access to coordination state (leases, handoffs, interrupts, tasks).
/// Backed today by the `coord` SQLite store; in tests, by a fixture.
pub trait CoordView: Send + Sync {
    fn active_leases(&self) -> Vec<LeaseSummary>;
    fn pending_handoffs(&self) -> Vec<HandoffSummary>;
    fn pending_interrupts(&self) -> Vec<InterruptSummary>;
    /// Supervisor task lifecycles, newest first. Empty when the `coord` feature
    /// is off so the TUI can render a "no supervisor" state without cfg.
    fn tasks(&self) -> Vec<TaskSummary>;
}

// ============================================================================
// Agent bus
// ============================================================================

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentDirectoryEntry {
    pub session_id: String,
    pub pid: u32,
    pub cwd: String,
    pub project: String,
    pub status: String,
    pub role: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RoleBinding {
    pub name: String,
    pub cwd_selector: String,
    pub last_session_id: Option<String>,
    pub last_seen: String,
    /// PID this role is bound to (#307). `None` for cwd-only bindings.
    pub pid: Option<u32>,
}

/// 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.
pub trait BusView: Send + Sync {
    fn list_agents(&self) -> Vec<AgentDirectoryEntry>;
    fn list_roles(&self) -> Vec<RoleBinding>;
}

// ============================================================================
// Actions (write surface)
// ============================================================================

/// 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.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ObservationInput {
    /// PID of the session the observation belongs to.
    pub session_pid: u32,
    /// Project label (usually the cwd basename).
    pub project: String,
    /// Tool the action targeted, when applicable ("Bash", "Write", …).
    pub tool: Option<String>,
    /// The command or input string the user ran/sent.
    pub command: Option<String>,
    /// Classification — `"user_approve"`, `"user_input"`, `"rule_approve"`,
    /// `"rule_deny"`, and friends. Kept as a string so callers can introduce
    /// new categories without a trait change.
    pub observed_action: String,
}

/// Whether a decision was about a session or about an orchestration task.
/// Mirrors `brain::decisions::DecisionType` without depending on it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum DecisionScope {
    Session,
    Orchestration,
}

impl DecisionScope {
    /// Wire label. Matches what `brain::decisions::DecisionType::as_label`
    /// writes to disk so the round-trip is stable.
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Session => "session",
            Self::Orchestration => "orchestration",
        }
    }
}

/// 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.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LogDecisionInput {
    /// PID of the session the decision applies to.
    pub session_pid: u32,
    /// Project label.
    pub project: String,
    /// Tool name the suggestion targeted.
    pub tool: Option<String>,
    /// Command / input string the suggestion targeted.
    pub command: Option<String>,
    /// The brain's suggestion the user is resolving.
    pub suggestion: PendingSuggestion,
    /// What the user did — `"accept"`, `"reject"`, `"deny_rule_override"`, etc.
    pub user_action: String,
    /// Whether this was a session decision or an orchestration decision.
    pub decision_type: DecisionScope,
    /// Why the user overrode a brain denial (if applicable).
    pub override_reason: Option<String>,
}

/// 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).
///
/// Each method is fallible — implementations return a `Result` rather than
/// silently swallowing errors so the TUI can surface failures in the status
/// bar instead of pretending an action succeeded.
///
/// **Not modeled here (intentionally):**
///
/// - `launch::*` — launching a new Claude Code session is wider than a single
///   call (cwd selection, model defaults, plugin propagation). Will get its
///   own trait once the TUI's launcher surface is refactored alongside #275.
/// - `mailbox::deliver_pending` — orchestrator-style mailbox delivery; should
///   eventually move to an `Orchestrator` trait, not `Actions`.
/// - `log_decision` (vs. `log_observation`) — currently only called from the
///   plugin gate path, not the TUI. Stays a direct call until a TUI site
///   needs it.
pub trait Actions: Send + Sync {
    /// Terminate the OS process with the given PID. The TUI uses this for
    /// "kill session" hotkeys.
    fn terminate_session(&self, pid: u32) -> Result<(), String>;

    /// Inject text into the session's terminal. Implementations pick the
    /// right backend (tmux, Kitty, etc.) from the session metadata.
    ///
    /// The `text` is sent verbatim — the caller is responsible for any
    /// trailing newline they want. Sanitization (e.g. neutralizing a leading
    /// `/`) belongs to the caller; this trait is a transport.
    fn inject_text(&self, session_id: &str, text: &str) -> Result<(), String>;

    /// Update the persisted brain gate mode. Reflected back through
    /// `BrainView::gate_mode` on the next call.
    fn set_gate_mode(&self, mode: BrainGateMode) -> Result<(), String>;

    /// Record an observation about a user action — non-LLM "the user did X."
    /// Drives the brain's outcome telemetry and preference distillation.
    fn log_observation(&self, observation: ObservationInput) -> Result<(), String>;

    /// Record a user's accept/reject decision on a brain suggestion. The
    /// distinction from `log_observation` is that `log_decision` carries
    /// the actual suggestion that was on screen — the brain pairs it with
    /// the user's response for outcome telemetry, counterfactual analysis,
    /// and few-shot retrieval.
    fn log_decision(&self, input: LogDecisionInput) -> Result<(), String>;

    /// Mark a past brain decision as canonical for teaching. Optional `note`
    /// is the operator's annotation. Used by the Brain Review surface.
    fn mark_canonical(&self, decision_id: &str, note: Option<String>) -> Result<(), String>;

    /// Bind an agent-bus role to a `(cwd, pid)` pair. The TUI calls this from
    /// the new role-bind key (Ctrl+R) so the operator can attach a role to a
    /// specific running Claude session without dropping to another terminal.
    /// Returns `Err` when the bus feature is compiled out or the DB write
    /// fails. See issue #307.
    fn bind_bus_role(&self, name: &str, cwd: &str, pid: u32) -> Result<(), String>;

    /// Cancel a supervisor task (move it to CANCELLED). Used by the Supervisor
    /// panel's one-key cancel (#368). `Err` when the `coord` feature is compiled
    /// out, the task is already terminal, or the store write fails.
    fn cancel_task(&self, task_id: &str) -> Result<(), String>;

    /// Set or clear the supervisor drain marker. When draining, the reconciler
    /// stops issuing new task assignments while letting running tasks finish.
    /// `Err` when the `coord` feature is compiled out.
    fn set_supervisor_drain(&self, draining: bool) -> Result<(), String>;

    /// Re-queue a failed/cancelled task (move it back to PENDING so the
    /// reconciler re-assigns it). `Err` for a DONE task (nothing to retry), a
    /// still-active task, or when the `coord` feature is compiled out.
    fn retry_task(&self, task_id: &str) -> Result<(), String>;

    /// Approve a NEEDS_HUMAN task — accept the work as-is and move it to DONE,
    /// overriding the verifier that escalated it. `Err` when the task isn't in
    /// NEEDS_HUMAN, or the `coord` feature is compiled out.
    fn approve_task(&self, task_id: &str) -> Result<(), String>;
}

// ============================================================================
// Hive actions — knowledge-store (`hive`) + transport (`relay`) reads/writes
// ============================================================================

/// Snapshot of local hive state the overlay reads to render the Hive tab.
///
/// Mirrors the binary's same-named struct, lifted here so the TUI can hold
/// it without depending on the binary's app module.
#[derive(Debug, Clone, Default)]
pub struct HiveViewSnapshot {
    /// Local relay identity (peer ID string). `None` when the `relay`
    /// feature is compiled out.
    pub identity: Option<String>,
    /// Known peers, paired with last-seen address when available.
    pub peers: Vec<(String, Option<String>)>,
}

/// Hive + relay surface the TUI needs to render the Skills and Hive panels.
///
/// Separate trait from `Actions` because the underlying subsystems are
/// feature-gated (`hive`, `relay`) — when those features are off the
/// implementation returns empty/no-op values rather than failing.
pub trait HiveActions: Send + Sync {
    /// Semantic keys (`skill:<lowered-name>`) of skills already shared into
    /// the local hive store. Used by the Skills overlay to mark "already
    /// shared" rows.
    fn shared_skill_keys(&self) -> std::collections::HashSet<String>;

    /// Share a discovered skill into the local hive store. Returns the new
    /// unit ID on success.
    fn share_skill(&self, skill: &crate::skills::DiscoveredSkill) -> Result<String, String>;

    /// Current view of the local relay identity + known peers for the Hive
    /// tab.
    fn hive_view_snapshot(&self) -> HiveViewSnapshot;
}

// ============================================================================
// Brain driver (stateful)
// ============================================================================

/// One pending brain suggestion the user can accept or reject. Mirrors the
/// binary's `brain::client::BrainSuggestion` without exposing brain types.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PendingSuggestion {
    /// PID of the session this suggestion applies to.
    pub pid: u32,
    /// String label of the suggested action — `"approve"`, `"deny"`,
    /// `"send"`, `"terminate"`. String to avoid pulling `RuleAction`'s enum
    /// shape into the contract (it's already in `claudectl-core::rules` but
    /// callers may want to add new categories without bumping the trait).
    pub action: String,
    /// Suggested message body (a prompt to inject, a rationale to surface).
    pub message: Option<String>,
    /// Why the brain suggested this — used for the detail panel and the
    /// rejection log.
    pub reasoning: String,
    /// 0.0–1.0 confidence the brain assigned.
    pub confidence: f64,
    /// Epoch seconds when the suggestion was created. Drives time-to-correct
    /// telemetry.
    pub suggested_at: u64,
}

/// 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.
///
/// Boxed as `Box<dyn BrainDriver>` rather than `Arc<dyn BrainDriver>`
/// because there is exactly one owner (the TUI's `App`) and every method
/// needs `&mut self`. Sharing across threads is not a goal here.
///
/// Implementations may be `None` — the brain is opt-in (`--brain` flag).
/// When the field is `None` the TUI renders without brain interaction.
pub trait BrainDriver: Send {
    /// Run one tick of the brain loop against the current session set and
    /// the operator's deny rules. Returns `(pid, status_message)` pairs
    /// for any actions the brain decided on this tick — the TUI surfaces
    /// the messages in the status bar.
    fn tick(
        &mut self,
        sessions: &[SessionSnapshot],
        deny_rules: &[crate::rules::AutoRule],
    ) -> Vec<(u32, String)>;

    /// Drop pending suggestions for sessions that have exited. Called every
    /// refresh so the pending map stays bounded by the live session count.
    fn cleanup(&mut self, sessions: &[SessionSnapshot]);

    /// User accepted the pending suggestion for `pid`. Implementations
    /// return the log message the TUI should surface (`None` when there's
    /// no suggestion to accept).
    fn accept(&mut self, pid: u32) -> Option<String>;

    /// User rejected the pending suggestion for `pid`. Returns the
    /// suggestion that was rejected — the TUI logs it for replay /
    /// counterfactual analysis.
    fn reject(&mut self, pid: u32) -> Option<PendingSuggestion>;

    /// Lookup the pending suggestion for `pid`, if any. Used by detail
    /// panels and the status bar.
    fn pending_for(&self, pid: u32) -> Option<PendingSuggestion>;

    /// Total pending suggestion count. Used by the status bar.
    fn pending_count(&self) -> usize;

    /// Drop every pending suggestion. Called when the brain mode flips
    /// off or the operator resets state.
    fn clear_pending(&mut self);

    /// Inject a pending suggestion for `pid`. Used by demo mode to fake
    /// brain activity for screenshots / recordings. Implementations may
    /// drop suggestions whose `action` string doesn't map to a known
    /// engine action (rather than erroring out) — demo is best-effort.
    fn set_pending(&mut self, suggestion: PendingSuggestion);
}

// ============================================================================
// Orchestrator
// ============================================================================

/// Tick the orchestration layer once per refresh: deliver pending mailbox
/// messages, deliver pending coordination interrupts, and bookkeep stale
/// rows in the underlying stores.
///
/// Each `deliver_*` method returns `(id, status_message)` tuples the TUI
/// surfaces in the status bar. `id` is a `u32` for mailbox (matching the
/// brain's per-PID queue) and a `String` for interrupts (matching the
/// coord interrupt_id). They differ deliberately — keeping the trait honest
/// to the underlying surfaces rather than papering over the distinction.
///
/// Unlike `CoordView` / `BrainView` which are read-only, this trait is
/// stateful: each call writes to the brain/coord SQLite stores. It still
/// boxes as `Arc<dyn>` because no method needs `&mut self` — implementations
/// open a connection per call.
///
/// Implementations may be no-ops when the relevant feature is off (e.g. the
/// `coord` feature is disabled at compile time), so call sites don't need
/// `#[cfg(feature = "...")]` guards.
pub trait Orchestrator: Send + Sync {
    /// Drain pending mailbox messages addressed to running sessions and
    /// deliver them to the live terminals. Used by `App::tick` to surface
    /// `"Brain → sess_X: 'go ahead'"` style messages.
    fn deliver_mailbox(&self, sessions: &[SessionSnapshot]) -> Vec<(u32, String)>;

    /// Deliver pending coordination interrupts (cross-agent signals) to
    /// running sessions. Returns `(interrupt_id, status_message)` tuples.
    fn deliver_interrupts(&self, sessions: &[SessionSnapshot]) -> Vec<(String, String)>;

    /// Expire stale leases and interrupts that have passed their deadline.
    /// Bookkeeping side-effect; best-effort, no return. Implementations
    /// log failures rather than propagating them.
    fn expire_stale(&self);
}

// ============================================================================
// Runtime aggregate
// ============================================================================

/// Single struct the binary builds at startup and hands to the TUI.
///
/// All fields are `Arc<dyn ...>` so the TUI doesn't care whether an impl is
/// a thin SQLite wrapper, a remote HTTP client, or an in-memory mock — they
/// all share the same shape.
#[derive(Clone)]
pub struct Runtime {
    pub sessions: Arc<dyn SessionSource>,
    pub brain: Arc<dyn BrainView>,
    pub coord: Arc<dyn CoordView>,
    pub bus: Arc<dyn BusView>,
    pub actions: Arc<dyn Actions>,
    pub review: Arc<dyn BrainReviewView>,
    pub orchestrator: Arc<dyn Orchestrator>,
    pub hive: Arc<dyn HiveActions>,
}

impl Runtime {
    // 8-trait composition root; each view is its own arc. Splitting this into
    // sub-records would just trade one wide ctor for several narrow ones with
    // the same total fan-out.
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        sessions: Arc<dyn SessionSource>,
        brain: Arc<dyn BrainView>,
        coord: Arc<dyn CoordView>,
        bus: Arc<dyn BusView>,
        actions: Arc<dyn Actions>,
        review: Arc<dyn BrainReviewView>,
        orchestrator: Arc<dyn Orchestrator>,
        hive: Arc<dyn HiveActions>,
    ) -> Self {
        Self {
            sessions,
            brain,
            coord,
            bus,
            actions,
            review,
            orchestrator,
            hive,
        }
    }
}

// ============================================================================
// MockRuntime — for tests in this crate and in claudectl-tui
// ============================================================================

/// In-memory runtime backed by `Vec`s 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.
///
/// `Actions` impls record their calls in `actions_log` so tests can assert
/// "the TUI invoked the right side-effect" without spying on real I/O.
#[derive(Default)]
pub struct MockRuntime {
    pub sessions: Vec<SessionSnapshot>,
    pub gate_mode: std::sync::Mutex<Option<BrainGateMode>>,
    pub decisions: Vec<DecisionSummary>,
    pub review_queue: Vec<ReviewItemSummary>,
    pub leases: Vec<LeaseSummary>,
    pub handoffs: Vec<HandoffSummary>,
    pub interrupts: Vec<InterruptSummary>,
    pub tasks: Vec<TaskSummary>,
    pub agents: Vec<AgentDirectoryEntry>,
    pub roles: Vec<RoleBinding>,
    pub actions_log: std::sync::Mutex<Vec<MockAction>>,
}

/// Recorded `Actions` calls. Tests use this to assert side-effect ordering
/// without needing a real terminal or filesystem.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MockAction {
    Terminate {
        pid: u32,
    },
    InjectText {
        session_id: String,
        text: String,
    },
    SetGateMode(BrainGateMode),
    LogObservation(ObservationInput),
    LogDecision(LogDecisionInput),
    MarkCanonical {
        decision_id: String,
        note: Option<String>,
    },
    BindBusRole {
        name: String,
        cwd: String,
        pid: u32,
    },
    CancelTask {
        task_id: String,
    },
    SetSupervisorDrain {
        draining: bool,
    },
    RetryTask {
        task_id: String,
    },
    ApproveTask {
        task_id: String,
    },
}

impl PartialEq for ObservationInput {
    fn eq(&self, other: &Self) -> bool {
        self.session_pid == other.session_pid
            && self.project == other.project
            && self.tool == other.tool
            && self.command == other.command
            && self.observed_action == other.observed_action
    }
}

impl Eq for ObservationInput {}

impl PartialEq for LogDecisionInput {
    fn eq(&self, other: &Self) -> bool {
        self.session_pid == other.session_pid
            && self.project == other.project
            && self.tool == other.tool
            && self.command == other.command
            && self.user_action == other.user_action
            && self.decision_type == other.decision_type
            && self.override_reason == other.override_reason
            // PendingSuggestion's field-by-field equality
            && self.suggestion.pid == other.suggestion.pid
            && self.suggestion.action == other.suggestion.action
            && self.suggestion.message == other.suggestion.message
            && self.suggestion.reasoning == other.suggestion.reasoning
    }
}

impl Eq for LogDecisionInput {}

impl MockRuntime {
    pub fn into_runtime(self) -> Runtime {
        let arc = Arc::new(self);
        Runtime::new(
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc,
        )
    }

    pub fn actions(&self) -> Vec<MockAction> {
        self.actions_log
            .lock()
            .expect("actions_log poisoned")
            .clone()
    }
}

impl SessionSource for MockRuntime {
    fn list(&self) -> Vec<SessionSnapshot> {
        self.sessions.clone()
    }
}

impl BrainView for MockRuntime {
    fn gate_mode(&self) -> BrainGateMode {
        self.gate_mode
            .lock()
            .expect("gate_mode poisoned")
            .unwrap_or(BrainGateMode::On)
    }
    fn recent_decisions(&self, n: usize) -> Vec<DecisionSummary> {
        self.decisions.iter().take(n).cloned().collect()
    }
    fn decision_count(&self) -> usize {
        self.decisions.len()
    }
}

impl CoordView for MockRuntime {
    fn active_leases(&self) -> Vec<LeaseSummary> {
        self.leases.clone()
    }
    fn pending_handoffs(&self) -> Vec<HandoffSummary> {
        self.handoffs.clone()
    }
    fn pending_interrupts(&self) -> Vec<InterruptSummary> {
        self.interrupts.clone()
    }
    fn tasks(&self) -> Vec<TaskSummary> {
        self.tasks.clone()
    }
}

impl BusView for MockRuntime {
    fn list_agents(&self) -> Vec<AgentDirectoryEntry> {
        self.agents.clone()
    }
    fn list_roles(&self) -> Vec<RoleBinding> {
        self.roles.clone()
    }
}

impl BrainReviewView for MockRuntime {
    fn all_decisions(&self) -> Vec<DecisionSummary> {
        self.decisions.clone()
    }
    fn review_queue(&self) -> Vec<ReviewItemSummary> {
        self.review_queue.clone()
    }
}

impl Orchestrator for MockRuntime {
    fn deliver_mailbox(&self, _sessions: &[SessionSnapshot]) -> Vec<(u32, String)> {
        Vec::new()
    }
    fn deliver_interrupts(&self, _sessions: &[SessionSnapshot]) -> Vec<(String, String)> {
        Vec::new()
    }
    fn expire_stale(&self) {}
}

impl HiveActions for MockRuntime {
    fn shared_skill_keys(&self) -> std::collections::HashSet<String> {
        std::collections::HashSet::new()
    }
    fn share_skill(&self, _skill: &crate::skills::DiscoveredSkill) -> Result<String, String> {
        Err("MockRuntime does not implement skill sharing".into())
    }
    fn hive_view_snapshot(&self) -> HiveViewSnapshot {
        HiveViewSnapshot::default()
    }
}

impl Actions for MockRuntime {
    fn terminate_session(&self, pid: u32) -> Result<(), String> {
        self.actions_log
            .lock()
            .expect("actions_log poisoned")
            .push(MockAction::Terminate { pid });
        Ok(())
    }
    fn inject_text(&self, session_id: &str, text: &str) -> Result<(), String> {
        self.actions_log
            .lock()
            .expect("actions_log poisoned")
            .push(MockAction::InjectText {
                session_id: session_id.into(),
                text: text.into(),
            });
        Ok(())
    }
    fn set_gate_mode(&self, mode: BrainGateMode) -> Result<(), String> {
        *self.gate_mode.lock().expect("gate_mode poisoned") = Some(mode);
        self.actions_log
            .lock()
            .expect("actions_log poisoned")
            .push(MockAction::SetGateMode(mode));
        Ok(())
    }
    fn log_observation(&self, observation: ObservationInput) -> Result<(), String> {
        self.actions_log
            .lock()
            .expect("actions_log poisoned")
            .push(MockAction::LogObservation(observation));
        Ok(())
    }
    fn log_decision(&self, input: LogDecisionInput) -> Result<(), String> {
        self.actions_log
            .lock()
            .expect("actions_log poisoned")
            .push(MockAction::LogDecision(input));
        Ok(())
    }
    fn mark_canonical(&self, decision_id: &str, note: Option<String>) -> Result<(), String> {
        self.actions_log
            .lock()
            .expect("actions_log poisoned")
            .push(MockAction::MarkCanonical {
                decision_id: decision_id.into(),
                note,
            });
        Ok(())
    }
    fn bind_bus_role(&self, name: &str, cwd: &str, pid: u32) -> Result<(), String> {
        self.actions_log
            .lock()
            .expect("actions_log poisoned")
            .push(MockAction::BindBusRole {
                name: name.into(),
                cwd: cwd.into(),
                pid,
            });
        Ok(())
    }
    fn cancel_task(&self, task_id: &str) -> Result<(), String> {
        self.actions_log
            .lock()
            .expect("actions_log poisoned")
            .push(MockAction::CancelTask {
                task_id: task_id.into(),
            });
        Ok(())
    }
    fn set_supervisor_drain(&self, draining: bool) -> Result<(), String> {
        self.actions_log
            .lock()
            .expect("actions_log poisoned")
            .push(MockAction::SetSupervisorDrain { draining });
        Ok(())
    }
    fn retry_task(&self, task_id: &str) -> Result<(), String> {
        self.actions_log
            .lock()
            .expect("actions_log poisoned")
            .push(MockAction::RetryTask {
                task_id: task_id.into(),
            });
        Ok(())
    }
    fn approve_task(&self, task_id: &str) -> Result<(), String> {
        self.actions_log
            .lock()
            .expect("actions_log poisoned")
            .push(MockAction::ApproveTask {
                task_id: task_id.into(),
            });
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn sample_session(id: &str) -> SessionSnapshot {
        SessionSnapshot {
            session_id: id.into(),
            pid: 12345,
            cwd: "/work/proj".into(),
            project_name: "proj".into(),
            status: "Processing".into(),
            cost_usd: 1.23,
            context_tokens: 4000,
            context_max: 200_000,
            last_message_ts: 1_780_000_000,
        }
    }

    #[test]
    fn mock_runtime_assembles_and_lists_sessions() {
        let mock = MockRuntime {
            sessions: vec![sample_session("sess_a"), sample_session("sess_b")],
            ..Default::default()
        };
        let rt = mock.into_runtime();
        let listed = rt.sessions.list();
        assert_eq!(listed.len(), 2);
        assert_eq!(listed[0].session_id, "sess_a");
    }

    #[test]
    fn session_detail_falls_back_to_list_scan() {
        let mock = MockRuntime {
            sessions: vec![sample_session("sess_a"), sample_session("sess_b")],
            ..Default::default()
        };
        let rt = mock.into_runtime();
        assert!(rt.sessions.detail("sess_a").is_some());
        assert!(rt.sessions.detail("sess_missing").is_none());
    }

    #[test]
    fn brain_view_returns_recent_decisions_with_cap() {
        let mock = MockRuntime {
            decisions: (0..5)
                .map(|i| DecisionSummary {
                    id: format!("dec_{i}"),
                    timestamp: format!("2026-06-06T00:00:0{i}Z"),
                    action: "approve".into(),
                    confidence: Some(0.9),
                    project: None,
                    tool: None,
                    pid: 0,
                    command: None,
                    reasoning: None,
                    user_action: None,
                    override_reason: None,
                    brain_decision_ms: None,
                    canonical: None,
                    cache_hit: None,
                    cost_usd: None,
                    model: None,
                    outcome_kind: None,
                    outcome_detail: None,
                    suggested_at: None,
                    resolved_at: None,
                })
                .collect(),
            ..Default::default()
        };
        let rt = mock.into_runtime();
        assert_eq!(rt.brain.recent_decisions(3).len(), 3);
        assert_eq!(rt.brain.decision_count(), 5);
        assert_eq!(rt.brain.gate_mode(), BrainGateMode::On);
    }

    #[test]
    fn coord_view_reports_empty_state_cleanly() {
        let rt = MockRuntime::default().into_runtime();
        assert!(rt.coord.active_leases().is_empty());
        assert!(rt.coord.pending_handoffs().is_empty());
        assert!(rt.coord.pending_interrupts().is_empty());
        assert!(rt.coord.tasks().is_empty());
    }

    #[test]
    fn coord_view_returns_task_fixture() {
        let mock = MockRuntime {
            tasks: vec![TaskSummary {
                id: "t1".into(),
                name: "ship the thing".into(),
                state: "running".into(),
                role: Some("backend".into()),
                attempts: 2,
                max_retries: 3,
                last_session_id: Some("sess-abcdef12".into()),
                last_verdict: Some("PASS".into()),
                cost_usd: 1.25,
                created_at: "2026-06-25T10:00:00Z".into(),
                updated_at: "2026-06-25T10:05:00Z".into(),
            }],
            ..Default::default()
        };
        let rt = mock.into_runtime();
        let tasks = rt.coord.tasks();
        assert_eq!(tasks.len(), 1);
        assert_eq!(tasks[0].state, "running");
        assert_eq!(tasks[0].attempts, 2);
    }

    #[test]
    fn bus_view_reports_empty_state_cleanly() {
        let rt = MockRuntime::default().into_runtime();
        assert!(rt.bus.list_agents().is_empty());
        assert!(rt.bus.list_roles().is_empty());
    }

    /// Smoke test that the trait shapes are usable behind `dyn`. If this
    /// compiles, the boxed-trait composition works.
    #[test]
    fn runtime_implements_clone_and_send() {
        fn assert_send<T: Send>() {}
        assert_send::<Runtime>();

        let rt = MockRuntime::default().into_runtime();
        let _rt2 = rt.clone();
    }

    #[test]
    fn actions_terminate_records_in_log() {
        let rt = MockRuntime::default().into_runtime();
        rt.actions.terminate_session(42).unwrap();
        rt.actions.terminate_session(43).unwrap();
        // No public mock accessor on Arc<dyn Actions>, but we can downcast
        // through the trait by going via the *original* Arc through inspecting
        // the trait's behavior — the integration test in the binary covers
        // that surface. Here we just assert the calls succeeded.
    }

    #[test]
    fn actions_task_writes_record_in_log() {
        let mock = MockRuntime::default();
        // MockRuntime itself implements Actions; call directly so we can read
        // the recorded log via the public `actions()` accessor.
        mock.cancel_task("t-1").unwrap();
        mock.set_supervisor_drain(true).unwrap();
        mock.retry_task("t-2").unwrap();
        mock.approve_task("t-3").unwrap();
        let actions = mock.actions();
        assert!(matches!(&actions[0], MockAction::CancelTask { task_id } if task_id == "t-1"));
        assert!(matches!(
            actions[1],
            MockAction::SetSupervisorDrain { draining: true }
        ));
        assert!(matches!(&actions[2], MockAction::RetryTask { task_id } if task_id == "t-2"));
        assert!(matches!(&actions[3], MockAction::ApproveTask { task_id } if task_id == "t-3"));
    }

    #[test]
    fn actions_set_gate_mode_round_trips_through_brain_view() {
        let mock = MockRuntime::default();
        let arc = Arc::new(mock);
        let rt = Runtime::new(
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
        );
        // Initial: default On.
        assert_eq!(rt.brain.gate_mode(), BrainGateMode::On);
        // Flip via Actions; observe via BrainView.
        rt.actions.set_gate_mode(BrainGateMode::Off).unwrap();
        assert_eq!(rt.brain.gate_mode(), BrainGateMode::Off);
        rt.actions.set_gate_mode(BrainGateMode::Auto).unwrap();
        assert_eq!(rt.brain.gate_mode(), BrainGateMode::Auto);
        // And the log captured both transitions.
        let calls = arc.actions();
        assert_eq!(
            calls,
            vec![
                MockAction::SetGateMode(BrainGateMode::Off),
                MockAction::SetGateMode(BrainGateMode::Auto),
            ]
        );
    }

    #[test]
    fn actions_log_observation_captures_full_input() {
        let mock = MockRuntime::default();
        let arc = Arc::new(mock);
        let rt = Runtime::new(
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
        );
        let obs = ObservationInput {
            session_pid: 12345,
            project: "claudectl".into(),
            tool: Some("Bash".into()),
            command: Some("cargo test".into()),
            observed_action: "user_approve".into(),
        };
        rt.actions.log_observation(obs.clone()).unwrap();
        let calls = arc.actions();
        assert_eq!(calls, vec![MockAction::LogObservation(obs)]);
    }

    #[test]
    fn actions_inject_text_and_mark_canonical_record_inputs() {
        let mock = MockRuntime::default();
        let arc = Arc::new(mock);
        let rt = Runtime::new(
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
            arc.clone(),
        );
        rt.actions.inject_text("sess_a", "/compact\n").unwrap();
        rt.actions
            .mark_canonical("dec_42", Some("nice catch".into()))
            .unwrap();
        let calls = arc.actions();
        assert_eq!(
            calls,
            vec![
                MockAction::InjectText {
                    session_id: "sess_a".into(),
                    text: "/compact\n".into(),
                },
                MockAction::MarkCanonical {
                    decision_id: "dec_42".into(),
                    note: Some("nice catch".into()),
                },
            ]
        );
    }
}