Merge pull request #884 from affaan-m/feat/ecc2-token-meter

feat(ecc2): token/cost meter widget

ecc2/Cargo.lock

@@ -332,6 +332,7 @@ dependencies = [
  "crossterm",
  "dirs",
  "git2",
+ "libc",
  "ratatui",
  "rusqlite",
  "serde",

ecc2/Cargo.toml

@@ -36,6 +36,7 @@ tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 # Error handling
 anyhow = "1"
 thiserror = "2"
+libc = "0.2"
 
 # Time
 chrono = { version = "0.4", features = ["serde"] }

ecc2/src/comms/mod.rs

@@ -13,7 +13,10 @@ pub enum MessageType {
     /// Response to a query
     Response { answer: String },
     /// Notification of completion
-    Completed { summary: String, files_changed: Vec<String> },
+    Completed {
+        summary: String,
+        files_changed: Vec<String>,
+    },
     /// Conflict detected (e.g., two agents editing the same file)
     Conflict { file: String, description: String },
 }

ecc2/src/config/mod.rs

@@ -3,6 +3,7 @@ use serde::{Deserialize, Serialize};
 use std::path::PathBuf;
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default)]
 pub struct Config {
     pub db_path: PathBuf,
     pub worktree_root: PathBuf,
@@ -11,6 +12,8 @@ pub struct Config {
     pub session_timeout_secs: u64,
     pub heartbeat_interval_secs: u64,
     pub default_agent: String,
+    pub cost_budget_usd: f64,
+    pub token_budget: u64,
     pub theme: Theme,
 }
 
@@ -31,6 +34,8 @@ impl Default for Config {
             session_timeout_secs: 3600,
             heartbeat_interval_secs: 30,
             default_agent: "claude".to_string(),
+            cost_budget_usd: 10.0,
+            token_budget: 500_000,
             theme: Theme::Dark,
         }
     }
@@ -52,3 +57,36 @@ impl Config {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::Config;
+
+    #[test]
+    fn default_includes_positive_budget_thresholds() {
+        let config = Config::default();
+
+        assert!(config.cost_budget_usd > 0.0);
+        assert!(config.token_budget > 0);
+    }
+
+    #[test]
+    fn missing_budget_fields_fall_back_to_defaults() {
+        let legacy_config = r#"
+db_path = "/tmp/ecc2.db"
+worktree_root = "/tmp/ecc-worktrees"
+max_parallel_sessions = 8
+max_parallel_worktrees = 6
+session_timeout_secs = 3600
+heartbeat_interval_secs = 30
+default_agent = "claude"
+theme = "Dark"
+"#;
+
+        let config: Config = toml::from_str(legacy_config).unwrap();
+        let defaults = Config::default();
+
+        assert_eq!(config.cost_budget_usd, defaults.cost_budget_usd);
+        assert_eq!(config.token_budget, defaults.token_budget);
+    }
+}

ecc2/src/main.rs

@@ -1,9 +1,9 @@
+mod comms;
 mod config;
+mod observability;
 mod session;
 mod tui;
 mod worktree;
-mod observability;
-mod comms;
 
 use anyhow::Result;
 use clap::Parser;
@@ -63,10 +63,13 @@ async fn main() -> Result<()> {
         Some(Commands::Dashboard) | None => {
             tui::app::run(db, cfg).await?;
         }
-        Some(Commands::Start { task, agent, worktree: use_worktree }) => {
-            let session_id = session::manager::create_session(
-                &db, &cfg, &task, &agent, use_worktree,
-            ).await?;
+        Some(Commands::Start {
+            task,
+            agent,
+            worktree: use_worktree,
+        }) => {
+            let session_id =
+                session::manager::create_session(&db, &cfg, &task, &agent, use_worktree).await?;
             println!("Session started: {session_id}");
         }
         Some(Commands::Sessions) => {

ecc2/src/session/manager.rs

@@ -1,8 +1,11 @@
-use anyhow::Result;
+use anyhow::{Context, Result};
 use std::fmt;
+use std::path::{Path, PathBuf};
+use std::process::Stdio;
+use tokio::process::Command;
 
-use super::{Session, SessionMetrics, SessionState};
 use super::store::StateStore;
+use super::{Session, SessionMetrics, SessionState};
 use crate::config::Config;
 use crate::worktree;
 
@@ -12,12 +15,67 @@ pub async fn create_session(
     task: &str,
     agent_type: &str,
     use_worktree: bool,
+) -> Result<String> {
+    let repo_root =
+        std::env::current_dir().context("Failed to resolve current working directory")?;
+    let agent_program = agent_program(agent_type)?;
+
+    create_session_in_dir(
+        db,
+        cfg,
+        task,
+        agent_type,
+        use_worktree,
+        &repo_root,
+        &agent_program,
+    )
+    .await
+}
+
+pub fn list_sessions(db: &StateStore) -> Result<Vec<Session>> {
+    db.list_sessions()
+}
+
+pub fn get_status(db: &StateStore, id: &str) -> Result<SessionStatus> {
+    let session = resolve_session(db, id)?;
+    Ok(SessionStatus(session))
+}
+
+pub async fn stop_session(db: &StateStore, id: &str) -> Result<()> {
+    stop_session_with_options(db, id, true).await
+}
+
+fn agent_program(agent_type: &str) -> Result<PathBuf> {
+    match agent_type {
+        "claude" => Ok(PathBuf::from("claude")),
+        other => anyhow::bail!("Unsupported agent type: {other}"),
+    }
+}
+
+fn resolve_session(db: &StateStore, id: &str) -> Result<Session> {
+    let session = if id == "latest" {
+        db.get_latest_session()?
+    } else {
+        db.get_session(id)?
+    };
+
+    session.ok_or_else(|| anyhow::anyhow!("Session not found: {id}"))
+}
+
+async fn create_session_in_dir(
+    db: &StateStore,
+    cfg: &Config,
+    task: &str,
+    agent_type: &str,
+    use_worktree: bool,
+    repo_root: &Path,
+    agent_program: &Path,
 ) -> Result<String> {
     let id = uuid::Uuid::new_v4().to_string()[..8].to_string();
     let now = chrono::Utc::now();
 
     let wt = if use_worktree {
-        Some(worktree::create_for_session(&id, cfg)?)
+        Some(worktree::create_for_session_in_repo(&id, cfg, repo_root)?)
     } else {
         None
     };
@@ -27,6 +85,7 @@ pub async fn create_session(
         task: task.to_string(),
         agent_type: agent_type.to_string(),
         state: SessionState::Pending,
+        pid: None,
         worktree: wt,
         created_at: now,
         updated_at: now,
@@ -34,25 +93,123 @@ pub async fn create_session(
     };
 
     db.insert_session(&session)?;
-    Ok(id)
+
+    let working_dir = session
+        .worktree
+        .as_ref()
+        .map(|worktree| worktree.path.as_path())
+        .unwrap_or(repo_root);
+
+    match spawn_claude_code(agent_program, task, &session.id, working_dir).await {
+        Ok(pid) => {
+            db.update_pid(&session.id, Some(pid))?;
+            db.update_state(&session.id, &SessionState::Running)?;
+            Ok(session.id)
+        }
+        Err(error) => {
+            db.update_state(&session.id, &SessionState::Failed)?;
+
+            if let Some(worktree) = session.worktree.as_ref() {
+                let _ = crate::worktree::remove(&worktree.path);
+            }
+
+            Err(error.context(format!("Failed to start session {}", session.id)))
+        }
+    }
 }
 
-pub fn list_sessions(db: &StateStore) -> Result<Vec<Session>> {
-    db.list_sessions()
+async fn spawn_claude_code(
+    agent_program: &Path,
+    task: &str,
+    session_id: &str,
+    working_dir: &Path,
+) -> Result<u32> {
+    let child = Command::new(agent_program)
+        .arg("--print")
+        .arg("--name")
+        .arg(format!("ecc-{session_id}"))
+        .arg(task)
+        .current_dir(working_dir)
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .spawn()
+        .with_context(|| {
+            format!(
+                "Failed to spawn Claude Code from {}",
+                agent_program.display()
+            )
+        })?;
+
+    child
+        .id()
+        .ok_or_else(|| anyhow::anyhow!("Claude Code did not expose a process id"))
 }
 
-pub fn get_status(db: &StateStore, id: &str) -> Result<SessionStatus> {
-    let session = db
-        .get_session(id)?
-        .ok_or_else(|| anyhow::anyhow!("Session not found: {id}"))?;
-    Ok(SessionStatus(session))
-}
+async fn stop_session_with_options(
+    db: &StateStore,
+    id: &str,
+    cleanup_worktree: bool,
+) -> Result<()> {
+    let session = resolve_session(db, id)?;
+
+    if let Some(pid) = session.pid {
+        kill_process(pid).await?;
+    }
+
+    db.update_pid(&session.id, None)?;
+    db.update_state(&session.id, &SessionState::Stopped)?;
+
+    if cleanup_worktree {
+        if let Some(worktree) = session.worktree.as_ref() {
+            crate::worktree::remove(&worktree.path)?;
+        }
+    }
 
-pub async fn stop_session(db: &StateStore, id: &str) -> Result<()> {
-    db.update_state(id, &SessionState::Stopped)?;
     Ok(())
 }
 
+#[cfg(unix)]
+async fn kill_process(pid: u32) -> Result<()> {
+    send_signal(pid, libc::SIGTERM)?;
+    tokio::time::sleep(std::time::Duration::from_millis(1200)).await;
+    send_signal(pid, libc::SIGKILL)?;
+    Ok(())
+}
+
+#[cfg(unix)]
+fn send_signal(pid: u32, signal: i32) -> Result<()> {
+    let outcome = unsafe { libc::kill(pid as i32, signal) };
+    if outcome == 0 {
+        return Ok(());
+    }
+
+    let error = std::io::Error::last_os_error();
+    if error.raw_os_error() == Some(libc::ESRCH) {
+        return Ok(());
+    }
+
+    Err(error).with_context(|| format!("Failed to kill process {pid}"))
+}
+
+#[cfg(not(unix))]
+async fn kill_process(pid: u32) -> Result<()> {
+    let status = Command::new("taskkill")
+        .args(["/F", "/PID", &pid.to_string()])
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .status()
+        .await
+        .with_context(|| format!("Failed to invoke taskkill for process {pid}"))?;
+
+    if status.success() {
+        Ok(())
+    } else {
+        anyhow::bail!("taskkill failed for process {pid}");
+    }
+}
+
 pub struct SessionStatus(Session);
 
 impl fmt::Display for SessionStatus {
@@ -62,6 +219,9 @@ impl fmt::Display for SessionStatus {
         writeln!(f, "Task:    {}", s.task)?;
         writeln!(f, "Agent:   {}", s.agent_type)?;
         writeln!(f, "State:   {}", s.state)?;
+        if let Some(pid) = s.pid {
+            writeln!(f, "PID:     {}", pid)?;
+        }
         if let Some(ref wt) = s.worktree {
             writeln!(f, "Branch:  {}", wt.branch)?;
             writeln!(f, "Worktree: {}", wt.path.display())?;
@@ -74,3 +234,255 @@ impl fmt::Display for SessionStatus {
         write!(f, "Updated: {}", s.updated_at)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::{Config, Theme};
+    use crate::session::{Session, SessionMetrics, SessionState};
+    use anyhow::{Context, Result};
+    use chrono::{Duration, Utc};
+    use std::fs;
+    use std::os::unix::fs::PermissionsExt;
+    use std::path::{Path, PathBuf};
+    use std::process::Command as StdCommand;
+    use std::thread;
+    use std::time::Duration as StdDuration;
+
+    struct TestDir {
+        path: PathBuf,
+    }
+
+    impl TestDir {
+        fn new(label: &str) -> Result<Self> {
+            let path =
+                std::env::temp_dir().join(format!("ecc2-{}-{}", label, uuid::Uuid::new_v4()));
+            fs::create_dir_all(&path)?;
+            Ok(Self { path })
+        }
+
+        fn path(&self) -> &Path {
+            &self.path
+        }
+    }
+
+    impl Drop for TestDir {
+        fn drop(&mut self) {
+            let _ = fs::remove_dir_all(&self.path);
+        }
+    }
+
+    fn build_config(root: &Path) -> Config {
+        Config {
+            db_path: root.join("state.db"),
+            worktree_root: root.join("worktrees"),
+            max_parallel_sessions: 4,
+            max_parallel_worktrees: 4,
+            session_timeout_secs: 60,
+            heartbeat_interval_secs: 5,
+            default_agent: "claude".to_string(),
+            theme: Theme::Dark,
+        }
+    }
+
+    fn build_session(id: &str, state: SessionState, updated_at: chrono::DateTime<Utc>) -> Session {
+        Session {
+            id: id.to_string(),
+            task: format!("task-{id}"),
+            agent_type: "claude".to_string(),
+            state,
+            pid: None,
+            worktree: None,
+            created_at: updated_at - Duration::minutes(1),
+            updated_at,
+            metrics: SessionMetrics::default(),
+        }
+    }
+
+    fn init_git_repo(path: &Path) -> Result<()> {
+        fs::create_dir_all(path)?;
+        run_git(path, ["init", "-q"])?;
+        fs::write(path.join("README.md"), "hello\n")?;
+        run_git(path, ["add", "README.md"])?;
+        run_git(
+            path,
+            [
+                "-c",
+                "user.name=ECC Tests",
+                "-c",
+                "user.email=ecc-tests@example.com",
+                "commit",
+                "-qm",
+                "init",
+            ],
+        )?;
+        Ok(())
+    }
+
+    fn run_git<const N: usize>(path: &Path, args: [&str; N]) -> Result<()> {
+        let status = StdCommand::new("git")
+            .args(args)
+            .current_dir(path)
+            .status()
+            .with_context(|| format!("failed to run git in {}", path.display()))?;
+
+        if !status.success() {
+            anyhow::bail!("git command failed in {}", path.display());
+        }
+
+        Ok(())
+    }
+
+    fn write_fake_claude(root: &Path) -> Result<(PathBuf, PathBuf)> {
+        let script_path = root.join("fake-claude.sh");
+        let log_path = root.join("fake-claude.log");
+        let script = format!(
+            "#!/usr/bin/env python3\nimport os\nimport pathlib\nimport signal\nimport sys\nimport time\n\nlog_path = pathlib.Path(r\"{}\")\nlog_path.write_text(os.getcwd() + \"\\n\", encoding=\"utf-8\")\nwith log_path.open(\"a\", encoding=\"utf-8\") as handle:\n    handle.write(\" \".join(sys.argv[1:]) + \"\\n\")\n\ndef handle_term(signum, frame):\n    raise SystemExit(0)\n\nsignal.signal(signal.SIGTERM, handle_term)\nwhile True:\n    time.sleep(0.1)\n",
+            log_path.display()
+        );
+
+        fs::write(&script_path, script)?;
+        let mut permissions = fs::metadata(&script_path)?.permissions();
+        permissions.set_mode(0o755);
+        fs::set_permissions(&script_path, permissions)?;
+
+        Ok((script_path, log_path))
+    }
+
+    fn wait_for_file(path: &Path) -> Result<String> {
+        for _ in 0..50 {
+            if path.exists() {
+                return fs::read_to_string(path)
+                    .with_context(|| format!("failed to read {}", path.display()));
+            }
+
+            thread::sleep(StdDuration::from_millis(20));
+        }
+
+        anyhow::bail!("timed out waiting for {}", path.display());
+    }
+
+    #[tokio::test(flavor = "current_thread")]
+    async fn create_session_spawns_process_and_marks_session_running() -> Result<()> {
+        let tempdir = TestDir::new("manager-create-session")?;
+        let repo_root = tempdir.path().join("repo");
+        init_git_repo(&repo_root)?;
+
+        let cfg = build_config(tempdir.path());
+        let db = StateStore::open(&cfg.db_path)?;
+        let (fake_claude, log_path) = write_fake_claude(tempdir.path())?;
+
+        let session_id = create_session_in_dir(
+            &db,
+            &cfg,
+            "implement lifecycle",
+            "claude",
+            false,
+            &repo_root,
+            &fake_claude,
+        )
+        .await?;
+
+        let session = db
+            .get_session(&session_id)?
+            .context("session should exist")?;
+        assert_eq!(session.state, SessionState::Running);
+        assert!(
+            session.pid.is_some(),
+            "spawned session should persist a pid"
+        );
+
+        let log = wait_for_file(&log_path)?;
+        assert!(log.contains(repo_root.to_string_lossy().as_ref()));
+        assert!(log.contains("--print"));
+        assert!(log.contains("implement lifecycle"));
+
+        stop_session_with_options(&db, &session_id, false).await?;
+        Ok(())
+    }
+
+    #[tokio::test(flavor = "current_thread")]
+    async fn stop_session_kills_process_and_optionally_cleans_worktree() -> Result<()> {
+        let tempdir = TestDir::new("manager-stop-session")?;
+        let repo_root = tempdir.path().join("repo");
+        init_git_repo(&repo_root)?;
+
+        let cfg = build_config(tempdir.path());
+        let db = StateStore::open(&cfg.db_path)?;
+        let (fake_claude, _) = write_fake_claude(tempdir.path())?;
+
+        let keep_id = create_session_in_dir(
+            &db,
+            &cfg,
+            "keep worktree",
+            "claude",
+            true,
+            &repo_root,
+            &fake_claude,
+        )
+        .await?;
+        let keep_session = db.get_session(&keep_id)?.context("keep session missing")?;
+        keep_session.pid.context("keep session pid missing")?;
+        let keep_worktree = keep_session
+            .worktree
+            .clone()
+            .context("keep session worktree missing")?
+            .path;
+
+        stop_session_with_options(&db, &keep_id, false).await?;
+
+        let stopped_keep = db
+            .get_session(&keep_id)?
+            .context("stopped keep session missing")?;
+        assert_eq!(stopped_keep.state, SessionState::Stopped);
+        assert_eq!(stopped_keep.pid, None);
+        assert!(
+            keep_worktree.exists(),
+            "worktree should remain when cleanup is disabled"
+        );
+
+        let cleanup_id = create_session_in_dir(
+            &db,
+            &cfg,
+            "cleanup worktree",
+            "claude",
+            true,
+            &repo_root,
+            &fake_claude,
+        )
+        .await?;
+        let cleanup_session = db
+            .get_session(&cleanup_id)?
+            .context("cleanup session missing")?;
+        let cleanup_worktree = cleanup_session
+            .worktree
+            .clone()
+            .context("cleanup session worktree missing")?
+            .path;
+
+        stop_session_with_options(&db, &cleanup_id, true).await?;
+        assert!(
+            !cleanup_worktree.exists(),
+            "worktree should be removed when cleanup is enabled"
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn get_status_supports_latest_alias() -> Result<()> {
+        let tempdir = TestDir::new("manager-latest-status")?;
+        let cfg = build_config(tempdir.path());
+        let db = StateStore::open(&cfg.db_path)?;
+        let older = Utc::now() - Duration::minutes(2);
+        let newer = Utc::now();
+
+        db.insert_session(&build_session("older", SessionState::Running, older))?;
+        db.insert_session(&build_session("newer", SessionState::Idle, newer))?;
+
+        let status = get_status(&db, "latest")?;
+        assert_eq!(status.0.id, "newer");
+
+        Ok(())
+    }
+}

ecc2/src/session/mod.rs

@@ -13,13 +13,14 @@ pub struct Session {
     pub task: String,
     pub agent_type: String,
     pub state: SessionState,
+    pub pid: Option<u32>,
     pub worktree: Option<WorktreeInfo>,
     pub created_at: DateTime<Utc>,
     pub updated_at: DateTime<Utc>,
     pub metrics: SessionMetrics,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub enum SessionState {
     Pending,
     Running,
@@ -42,6 +43,46 @@ impl fmt::Display for SessionState {
     }
 }
 
+impl SessionState {
+    pub fn can_transition_to(&self, next: &Self) -> bool {
+        if self == next {
+            return true;
+        }
+
+        matches!(
+            (self, next),
+            (
+                SessionState::Pending,
+                SessionState::Running | SessionState::Failed | SessionState::Stopped
+            ) | (
+                SessionState::Running,
+                SessionState::Idle
+                    | SessionState::Completed
+                    | SessionState::Failed
+                    | SessionState::Stopped
+            ) | (
+                SessionState::Idle,
+                SessionState::Running
+                    | SessionState::Completed
+                    | SessionState::Failed
+                    | SessionState::Stopped
+            ) | (SessionState::Completed, SessionState::Stopped)
+                | (SessionState::Failed, SessionState::Stopped)
+        )
+    }
+
+    pub fn from_db_value(value: &str) -> Self {
+        match value {
+            "running" => SessionState::Running,
+            "idle" => SessionState::Idle,
+            "completed" => SessionState::Completed,
+            "failed" => SessionState::Failed,
+            "stopped" => SessionState::Stopped,
+            _ => SessionState::Pending,
+        }
+    }
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct WorktreeInfo {
     pub path: PathBuf,

ecc2/src/session/store.rs

@@ -1,5 +1,5 @@
-use anyhow::Result;
-use rusqlite::Connection;
+use anyhow::{Context, Result};
+use rusqlite::{Connection, OptionalExtension};
 use std::path::Path;
 
 use super::{Session, SessionMetrics, SessionState};
@@ -24,6 +24,7 @@ impl StateStore {
                 task TEXT NOT NULL,
                 agent_type TEXT NOT NULL,
                 state TEXT NOT NULL DEFAULT 'pending',
+                pid INTEGER,
                 worktree_path TEXT,
                 worktree_branch TEXT,
                 worktree_base TEXT,
@@ -62,18 +63,40 @@ impl StateStore {
             CREATE INDEX IF NOT EXISTS idx_messages_to ON messages(to_session, read);
             ",
         )?;
+        self.ensure_session_columns()?;
         Ok(())
     }
 
+    fn ensure_session_columns(&self) -> Result<()> {
+        if !self.has_column("sessions", "pid")? {
+            self.conn
+                .execute("ALTER TABLE sessions ADD COLUMN pid INTEGER", [])
+                .context("Failed to add pid column to sessions table")?;
+        }
+
+        Ok(())
+    }
+
+    fn has_column(&self, table: &str, column: &str) -> Result<bool> {
+        let pragma = format!("PRAGMA table_info({table})");
+        let mut stmt = self.conn.prepare(&pragma)?;
+        let columns = stmt
+            .query_map([], |row| row.get::<_, String>(1))?
+            .collect::<std::result::Result<Vec<_>, _>>()?;
+
+        Ok(columns.iter().any(|existing| existing == column))
+    }
+
     pub fn insert_session(&self, session: &Session) -> Result<()> {
         self.conn.execute(
-            "INSERT INTO sessions (id, task, agent_type, state, worktree_path, worktree_branch, worktree_base, created_at, updated_at)
-             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)",
+            "INSERT INTO sessions (id, task, agent_type, state, pid, worktree_path, worktree_branch, worktree_base, created_at, updated_at)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)",
             rusqlite::params![
                 session.id,
                 session.task,
                 session.agent_type,
                 session.state.to_string(),
+                session.pid.map(i64::from),
                 session.worktree.as_ref().map(|w| w.path.to_string_lossy().to_string()),
                 session.worktree.as_ref().map(|w| w.branch.clone()),
                 session.worktree.as_ref().map(|w| w.base_branch.clone()),
@@ -85,7 +108,26 @@ impl StateStore {
     }
 
     pub fn update_state(&self, session_id: &str, state: &SessionState) -> Result<()> {
-        self.conn.execute(
+        let current_state = self
+            .conn
+            .query_row(
+                "SELECT state FROM sessions WHERE id = ?1",
+                [session_id],
+                |row| row.get::<_, String>(0),
+            )
+            .optional()?
+            .map(|raw| SessionState::from_db_value(&raw))
+            .ok_or_else(|| anyhow::anyhow!("Session not found: {session_id}"))?;
+
+        if !current_state.can_transition_to(state) {
+            anyhow::bail!(
+                "Invalid session state transition: {} -> {}",
+                current_state,
+                state
+            );
+        }
+
+        let updated = self.conn.execute(
             "UPDATE sessions SET state = ?1, updated_at = ?2 WHERE id = ?3",
             rusqlite::params![
                 state.to_string(),
@@ -93,6 +135,28 @@ impl StateStore {
                 session_id,
             ],
         )?;
+
+        if updated == 0 {
+            anyhow::bail!("Session not found: {session_id}");
+        }
+
+        Ok(())
+    }
+
+    pub fn update_pid(&self, session_id: &str, pid: Option<u32>) -> Result<()> {
+        let updated = self.conn.execute(
+            "UPDATE sessions SET pid = ?1, updated_at = ?2 WHERE id = ?3",
+            rusqlite::params![
+                pid.map(i64::from),
+                chrono::Utc::now().to_rfc3339(),
+                session_id,
+            ],
+        )?;
+
+        if updated == 0 {
+            anyhow::bail!("Session not found: {session_id}");
+        }
+
         Ok(())
     }
 
@@ -114,7 +178,7 @@ impl StateStore {
 
     pub fn list_sessions(&self) -> Result<Vec<Session>> {
         let mut stmt = self.conn.prepare(
-            "SELECT id, task, agent_type, state, worktree_path, worktree_branch, worktree_base,
+            "SELECT id, task, agent_type, state, pid, worktree_path, worktree_branch, worktree_base,
                     tokens_used, tool_calls, files_changed, duration_secs, cost_usd,
                     created_at, updated_at
              FROM sessions ORDER BY updated_at DESC",
@@ -123,30 +187,24 @@ impl StateStore {
         let sessions = stmt
             .query_map([], |row| {
                 let state_str: String = row.get(3)?;
-                let state = match state_str.as_str() {
-                    "running" => SessionState::Running,
-                    "idle" => SessionState::Idle,
-                    "completed" => SessionState::Completed,
-                    "failed" => SessionState::Failed,
-                    "stopped" => SessionState::Stopped,
-                    _ => SessionState::Pending,
-                };
+                let state = SessionState::from_db_value(&state_str);
 
-                let worktree_path: Option<String> = row.get(4)?;
+                let worktree_path: Option<String> = row.get(5)?;
                 let worktree = worktree_path.map(|p| super::WorktreeInfo {
                     path: std::path::PathBuf::from(p),
-                    branch: row.get::<_, String>(5).unwrap_or_default(),
-                    base_branch: row.get::<_, String>(6).unwrap_or_default(),
+                    branch: row.get::<_, String>(6).unwrap_or_default(),
+                    base_branch: row.get::<_, String>(7).unwrap_or_default(),
                 });
 
-                let created_str: String = row.get(12)?;
-                let updated_str: String = row.get(13)?;
+                let created_str: String = row.get(13)?;
+                let updated_str: String = row.get(14)?;
 
                 Ok(Session {
                     id: row.get(0)?,
                     task: row.get(1)?,
                     agent_type: row.get(2)?,
                     state,
+                    pid: row.get::<_, Option<u32>>(4)?,
                     worktree,
                     created_at: chrono::DateTime::parse_from_rfc3339(&created_str)
                         .unwrap_or_default()
@@ -155,11 +213,11 @@ impl StateStore {
                         .unwrap_or_default()
                         .with_timezone(&chrono::Utc),
                     metrics: SessionMetrics {
-                        tokens_used: row.get(7)?,
-                        tool_calls: row.get(8)?,
-                        files_changed: row.get(9)?,
-                        duration_secs: row.get(10)?,
-                        cost_usd: row.get(11)?,
+                        tokens_used: row.get(8)?,
+                        tool_calls: row.get(9)?,
+                        files_changed: row.get(10)?,
+                        duration_secs: row.get(11)?,
+                        cost_usd: row.get(12)?,
                     },
                 })
             })?
@@ -168,18 +226,17 @@ impl StateStore {
         Ok(sessions)
     }
 
-    pub fn get_session(&self, id: &str) -> Result<Option<Session>> {
-        let sessions = self.list_sessions()?;
-        Ok(sessions.into_iter().find(|s| s.id == id || s.id.starts_with(id)))
+    pub fn get_latest_session(&self) -> Result<Option<Session>> {
+        Ok(self.list_sessions()?.into_iter().next())
     }
 
-    pub fn send_message(
-        &self,
-        from: &str,
-        to: &str,
-        content: &str,
-        msg_type: &str,
-    ) -> Result<()> {
+    pub fn get_session(&self, id: &str) -> Result<Option<Session>> {
+        let sessions = self.list_sessions()?;
+        Ok(sessions
+            .into_iter()
+            .find(|s| s.id == id || s.id.starts_with(id)))
+    }
+    pub fn send_message(&self, from: &str, to: &str, content: &str, msg_type: &str) -> Result<()> {
         self.conn.execute(
             "INSERT INTO messages (from_session, to_session, content, msg_type, timestamp)
              VALUES (?1, ?2, ?3, ?4, ?5)",
@@ -188,3 +245,105 @@ impl StateStore {
         Ok(())
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::session::{Session, SessionMetrics, SessionState};
+    use chrono::{Duration, Utc};
+    use std::fs;
+    use std::path::{Path, PathBuf};
+
+    struct TestDir {
+        path: PathBuf,
+    }
+
+    impl TestDir {
+        fn new(label: &str) -> Result<Self> {
+            let path =
+                std::env::temp_dir().join(format!("ecc2-{}-{}", label, uuid::Uuid::new_v4()));
+            fs::create_dir_all(&path)?;
+            Ok(Self { path })
+        }
+
+        fn path(&self) -> &Path {
+            &self.path
+        }
+    }
+
+    impl Drop for TestDir {
+        fn drop(&mut self) {
+            let _ = fs::remove_dir_all(&self.path);
+        }
+    }
+
+    fn build_session(id: &str, state: SessionState) -> Session {
+        let now = Utc::now();
+        Session {
+            id: id.to_string(),
+            task: "task".to_string(),
+            agent_type: "claude".to_string(),
+            state,
+            pid: None,
+            worktree: None,
+            created_at: now - Duration::minutes(1),
+            updated_at: now,
+            metrics: SessionMetrics::default(),
+        }
+    }
+
+    #[test]
+    fn update_state_rejects_invalid_terminal_transition() -> Result<()> {
+        let tempdir = TestDir::new("store-invalid-transition")?;
+        let db = StateStore::open(&tempdir.path().join("state.db"))?;
+
+        db.insert_session(&build_session("done", SessionState::Completed))?;
+
+        let error = db
+            .update_state("done", &SessionState::Running)
+            .expect_err("completed sessions must not transition back to running");
+
+        assert!(error
+            .to_string()
+            .contains("Invalid session state transition"));
+        Ok(())
+    }
+
+    #[test]
+    fn open_migrates_existing_sessions_table_with_pid_column() -> Result<()> {
+        let tempdir = TestDir::new("store-migration")?;
+        let db_path = tempdir.path().join("state.db");
+
+        let conn = Connection::open(&db_path)?;
+        conn.execute_batch(
+            "
+            CREATE TABLE sessions (
+                id TEXT PRIMARY KEY,
+                task TEXT NOT NULL,
+                agent_type TEXT NOT NULL,
+                state TEXT NOT NULL DEFAULT 'pending',
+                worktree_path TEXT,
+                worktree_branch TEXT,
+                worktree_base TEXT,
+                tokens_used INTEGER DEFAULT 0,
+                tool_calls INTEGER DEFAULT 0,
+                files_changed INTEGER DEFAULT 0,
+                duration_secs INTEGER DEFAULT 0,
+                cost_usd REAL DEFAULT 0.0,
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL
+            );
+            ",
+        )?;
+        drop(conn);
+
+        let db = StateStore::open(&db_path)?;
+        let mut stmt = db.conn.prepare("PRAGMA table_info(sessions)")?;
+        let column_names = stmt
+            .query_map([], |row| row.get::<_, String>(1))?
+            .collect::<std::result::Result<Vec<_>, _>>()?;
+
+        assert!(column_names.iter().any(|column| column == "pid"));
+        Ok(())
+    }
+}

ecc2/src/tui/dashboard.rs

@@ -1,11 +1,12 @@
 use ratatui::{
     prelude::*,
-    widgets::{Block, Borders, List, ListItem, Paragraph, Tabs},
+    widgets::{Block, Borders, List, ListItem, Paragraph, Tabs, Wrap},
 };
 
+use super::widgets::{budget_state, format_currency, format_token_count, BudgetState, TokenMeter};
 use crate::config::Config;
-use crate::session::{Session, SessionState};
 use crate::session::store::StateStore;
+use crate::session::{Session, SessionState};
 
 pub struct Dashboard {
     db: StateStore,
@@ -24,6 +25,15 @@ enum Pane {
     Metrics,
 }
 
+#[derive(Debug, Clone, Copy)]
+struct AggregateUsage {
+    total_tokens: u64,
+    total_cost_usd: f64,
+    token_state: BudgetState,
+    cost_state: BudgetState,
+    overall_state: BudgetState,
+}
+
 impl Dashboard {
     pub fn new(db: StateStore, cfg: Config) -> Self {
         let sessions = db.list_sessions().unwrap_or_default();
@@ -42,7 +52,7 @@ impl Dashboard {
         let chunks = Layout::default()
             .direction(Direction::Vertical)
             .constraints([
-                Constraint::Length(3),  // Header
+                Constraint::Length(3), // Header
                 Constraint::Min(10),   // Main content
                 Constraint::Length(3), // Status bar
             ])
@@ -79,7 +89,11 @@ impl Dashboard {
     }
 
     fn render_header(&self, frame: &mut Frame, area: Rect) {
-        let running = self.sessions.iter().filter(|s| s.state == SessionState::Running).count();
+        let running = self
+            .sessions
+            .iter()
+            .filter(|s| s.state == SessionState::Running)
+            .count();
         let total = self.sessions.len();
 
         let title = format!(" ECC 2.0 | {running} running / {total} total ");
@@ -90,7 +104,11 @@ impl Dashboard {
                 Pane::Output => 1,
                 Pane::Metrics => 2,
             })
-            .highlight_style(Style::default().fg(Color::Cyan).add_modifier(Modifier::BOLD));
+            .highlight_style(
+                Style::default()
+                    .fg(Color::Cyan)
+                    .add_modifier(Modifier::BOLD),
+            );
 
         frame.render_widget(tabs, area);
     }
@@ -110,11 +128,18 @@ impl Dashboard {
                     SessionState::Pending => "◌",
                 };
                 let style = if i == self.selected_session {
-                    Style::default().fg(Color::Cyan).add_modifier(Modifier::BOLD)
+                    Style::default()
+                        .fg(Color::Cyan)
+                        .add_modifier(Modifier::BOLD)
                 } else {
                     Style::default()
                 };
-                let text = format!("{state_icon} {} [{}] {}", &s.id[..8.min(s.id.len())], s.agent_type, s.task);
+                let text = format!(
+                    "{state_icon} {} [{}] {}",
+                    &s.id[..8.min(s.id.len())],
+                    s.agent_type,
+                    s.task
+                );
                 ListItem::new(text).style(style)
             })
             .collect();
@@ -136,7 +161,10 @@ impl Dashboard {
 
     fn render_output(&self, frame: &mut Frame, area: Rect) {
         let content = if let Some(session) = self.sessions.get(self.selected_session) {
-            format!("Agent output for session {}...\n\n(Live streaming coming soon)", session.id)
+            format!(
+                "Agent output for session {}...\n\n(Live streaming coming soon)",
+                session.id
+            )
         } else {
             "No sessions. Press 'n' to start one.".to_string()
         };
@@ -157,37 +185,87 @@ impl Dashboard {
     }
 
     fn render_metrics(&self, frame: &mut Frame, area: Rect) {
-        let content = if let Some(session) = self.sessions.get(self.selected_session) {
-            let m = &session.metrics;
-            format!(
-                "Tokens: {} | Tools: {} | Files: {} | Cost: ${:.4} | Duration: {}s",
-                m.tokens_used, m.tool_calls, m.files_changed, m.cost_usd, m.duration_secs
-            )
-        } else {
-            "No metrics available".to_string()
-        };
-
         let border_style = if self.selected_pane == Pane::Metrics {
             Style::default().fg(Color::Cyan)
         } else {
             Style::default()
         };
 
-        let paragraph = Paragraph::new(content).block(
-            Block::default()
-                .borders(Borders::ALL)
-                .title(" Metrics ")
-                .border_style(border_style),
+        let block = Block::default()
+            .borders(Borders::ALL)
+            .title(" Metrics ")
+            .border_style(border_style);
+        let inner = block.inner(area);
+        frame.render_widget(block, area);
+
+        if inner.is_empty() {
+            return;
+        }
+
+        let chunks = Layout::default()
+            .direction(Direction::Vertical)
+            .constraints([
+                Constraint::Length(2),
+                Constraint::Length(2),
+                Constraint::Min(1),
+            ])
+            .split(inner);
+
+        let aggregate = self.aggregate_usage();
+        frame.render_widget(
+            TokenMeter::tokens(
+                "Token Budget",
+                aggregate.total_tokens,
+                self.cfg.token_budget,
+            ),
+            chunks[0],
+        );
+        frame.render_widget(
+            TokenMeter::currency(
+                "Cost Budget",
+                aggregate.total_cost_usd,
+                self.cfg.cost_budget_usd,
+            ),
+            chunks[1],
+        );
+        frame.render_widget(
+            Paragraph::new(self.selected_session_metrics_text()).wrap(Wrap { trim: true }),
+            chunks[2],
         );
-        frame.render_widget(paragraph, area);
     }
 
     fn render_status_bar(&self, frame: &mut Frame, area: Rect) {
         let text = " [n]ew session  [s]top  [Tab] switch pane  [j/k] scroll  [?] help  [q]uit ";
-        let paragraph = Paragraph::new(text)
-            .style(Style::default().fg(Color::DarkGray))
-            .block(Block::default().borders(Borders::ALL));
-        frame.render_widget(paragraph, area);
+        let aggregate = self.aggregate_usage();
+        let (summary_text, summary_style) = self.aggregate_cost_summary();
+        let block = Block::default()
+            .borders(Borders::ALL)
+            .border_style(aggregate.overall_state.style());
+        let inner = block.inner(area);
+        frame.render_widget(block, area);
+
+        if inner.is_empty() {
+            return;
+        }
+
+        let summary_width = summary_text
+            .len()
+            .min(inner.width.saturating_sub(1) as usize) as u16;
+        let chunks = Layout::default()
+            .direction(Direction::Horizontal)
+            .constraints([Constraint::Min(1), Constraint::Length(summary_width)])
+            .split(inner);
+
+        frame.render_widget(
+            Paragraph::new(text).style(Style::default().fg(Color::DarkGray)),
+            chunks[0],
+        );
+        frame.render_widget(
+            Paragraph::new(summary_text)
+                .style(summary_style)
+                .alignment(Alignment::Right),
+            chunks[1],
+        );
     }
 
     fn render_help(&self, frame: &mut Frame, area: Rect) {
@@ -270,4 +348,143 @@ impl Dashboard {
         // Periodic refresh every few ticks
         self.sessions = self.db.list_sessions().unwrap_or_default();
     }
+
+    fn aggregate_usage(&self) -> AggregateUsage {
+        let total_tokens = self
+            .sessions
+            .iter()
+            .map(|session| session.metrics.tokens_used)
+            .sum();
+        let total_cost_usd = self
+            .sessions
+            .iter()
+            .map(|session| session.metrics.cost_usd)
+            .sum::<f64>();
+        let token_state = budget_state(total_tokens as f64, self.cfg.token_budget as f64);
+        let cost_state = budget_state(total_cost_usd, self.cfg.cost_budget_usd);
+
+        AggregateUsage {
+            total_tokens,
+            total_cost_usd,
+            token_state,
+            cost_state,
+            overall_state: token_state.max(cost_state),
+        }
+    }
+
+    fn selected_session_metrics_text(&self) -> String {
+        if let Some(session) = self.sessions.get(self.selected_session) {
+            let metrics = &session.metrics;
+            format!(
+                "Selected {} [{}]\nTokens {} | Tools {} | Files {}\nCost ${:.4} | Duration {}s",
+                &session.id[..8.min(session.id.len())],
+                session.state,
+                format_token_count(metrics.tokens_used),
+                metrics.tool_calls,
+                metrics.files_changed,
+                metrics.cost_usd,
+                metrics.duration_secs
+            )
+        } else {
+            "No metrics available".to_string()
+        }
+    }
+
+    fn aggregate_cost_summary(&self) -> (String, Style) {
+        let aggregate = self.aggregate_usage();
+        let mut text = if self.cfg.cost_budget_usd > 0.0 {
+            format!(
+                "Aggregate cost {} / {}",
+                format_currency(aggregate.total_cost_usd),
+                format_currency(self.cfg.cost_budget_usd),
+            )
+        } else {
+            format!(
+                "Aggregate cost {} (no budget)",
+                format_currency(aggregate.total_cost_usd)
+            )
+        };
+
+        match aggregate.overall_state {
+            BudgetState::Warning => text.push_str(" | Budget warning"),
+            BudgetState::OverBudget => text.push_str(" | Budget exceeded"),
+            _ => {}
+        }
+
+        (text, aggregate.overall_state.style())
+    }
+
+    fn aggregate_cost_summary_text(&self) -> String {
+        self.aggregate_cost_summary().0
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::Path;
+
+    use chrono::Utc;
+
+    use super::Dashboard;
+    use crate::config::Config;
+    use crate::session::store::StateStore;
+    use crate::session::{Session, SessionMetrics, SessionState};
+    use crate::tui::widgets::BudgetState;
+
+    #[test]
+    fn aggregate_usage_sums_tokens_and_cost_with_warning_state() {
+        let db = StateStore::open(Path::new(":memory:")).unwrap();
+        let mut cfg = Config::default();
+        cfg.token_budget = 10_000;
+        cfg.cost_budget_usd = 10.0;
+
+        let mut dashboard = Dashboard::new(db, cfg);
+        dashboard.sessions = vec![
+            session("sess-1", 4_000, 3.50),
+            session("sess-2", 4_500, 4.80),
+        ];
+
+        let aggregate = dashboard.aggregate_usage();
+
+        assert_eq!(aggregate.total_tokens, 8_500);
+        assert!((aggregate.total_cost_usd - 8.30).abs() < 1e-9);
+        assert_eq!(aggregate.token_state, BudgetState::Warning);
+        assert_eq!(aggregate.cost_state, BudgetState::Warning);
+        assert_eq!(aggregate.overall_state, BudgetState::Warning);
+    }
+
+    #[test]
+    fn aggregate_cost_summary_mentions_total_cost() {
+        let db = StateStore::open(Path::new(":memory:")).unwrap();
+        let mut cfg = Config::default();
+        cfg.cost_budget_usd = 10.0;
+
+        let mut dashboard = Dashboard::new(db, cfg);
+        dashboard.sessions = vec![session("sess-1", 3_500, 8.25)];
+
+        assert_eq!(
+            dashboard.aggregate_cost_summary_text(),
+            "Aggregate cost $8.25 / $10.00 | Budget warning"
+        );
+    }
+
+    fn session(id: &str, tokens_used: u64, cost_usd: f64) -> Session {
+        let now = Utc::now();
+        Session {
+            id: id.to_string(),
+            task: "Budget tracking".to_string(),
+            agent_type: "claude".to_string(),
+            state: SessionState::Running,
+            worktree: None,
+            created_at: now,
+            updated_at: now,
+            metrics: SessionMetrics {
+                tokens_used,
+                tool_calls: 0,
+                files_changed: 0,
+                duration_secs: 0,
+                cost_usd,
+            },
+        }
+    }
 }

ecc2/src/tui/widgets.rs

@@ -1,6 +1,281 @@
-// Custom TUI widgets for ECC 2.0
-// TODO: Implement custom widgets:
-// - TokenMeter: visual token usage bar with budget threshold
-// - DiffViewer: side-by-side syntax-highlighted diff display
-// - ProgressTimeline: session timeline with tool call markers
-// - AgentTree: hierarchical view of parent/child agent sessions
+use ratatui::{
+    prelude::*,
+    text::{Line, Span},
+    widgets::{Gauge, Paragraph, Widget},
+};
+
+pub(crate) const WARNING_THRESHOLD: f64 = 0.8;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub(crate) enum BudgetState {
+    Unconfigured,
+    Normal,
+    Warning,
+    OverBudget,
+}
+
+impl BudgetState {
+    pub(crate) const fn is_warning(self) -> bool {
+        matches!(self, Self::Warning | Self::OverBudget)
+    }
+
+    fn badge(self) -> Option<&'static str> {
+        match self {
+            Self::Warning => Some("warning"),
+            Self::OverBudget => Some("over budget"),
+            Self::Unconfigured => Some("no budget"),
+            Self::Normal => None,
+        }
+    }
+
+    pub(crate) fn style(self) -> Style {
+        let base = Style::default().fg(match self {
+            Self::Unconfigured => Color::DarkGray,
+            Self::Normal => Color::DarkGray,
+            Self::Warning => Color::Yellow,
+            Self::OverBudget => Color::Red,
+        });
+
+        if self.is_warning() {
+            base.add_modifier(Modifier::BOLD)
+        } else {
+            base
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy)]
+enum MeterFormat {
+    Tokens,
+    Currency,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct TokenMeter<'a> {
+    title: &'a str,
+    used: f64,
+    budget: f64,
+    format: MeterFormat,
+}
+
+impl<'a> TokenMeter<'a> {
+    pub(crate) fn tokens(title: &'a str, used: u64, budget: u64) -> Self {
+        Self {
+            title,
+            used: used as f64,
+            budget: budget as f64,
+            format: MeterFormat::Tokens,
+        }
+    }
+
+    pub(crate) fn currency(title: &'a str, used: f64, budget: f64) -> Self {
+        Self {
+            title,
+            used,
+            budget,
+            format: MeterFormat::Currency,
+        }
+    }
+
+    pub(crate) fn state(&self) -> BudgetState {
+        budget_state(self.used, self.budget)
+    }
+
+    fn ratio(&self) -> f64 {
+        budget_ratio(self.used, self.budget)
+    }
+
+    fn clamped_ratio(&self) -> f64 {
+        self.ratio().clamp(0.0, 1.0)
+    }
+
+    fn title_line(&self) -> Line<'static> {
+        let mut spans = vec![Span::styled(
+            self.title.to_string(),
+            Style::default()
+                .fg(Color::Gray)
+                .add_modifier(Modifier::BOLD),
+        )];
+
+        if let Some(badge) = self.state().badge() {
+            spans.push(Span::raw(" "));
+            spans.push(Span::styled(format!("[{badge}]"), self.state().style()));
+        }
+
+        Line::from(spans)
+    }
+
+    fn display_label(&self) -> String {
+        if self.budget <= 0.0 {
+            return match self.format {
+                MeterFormat::Tokens => format!("{} tok used | no budget", self.used_label()),
+                MeterFormat::Currency => format!("{} spent | no budget", self.used_label()),
+            };
+        }
+
+        format!(
+            "{} / {}{} ({}%)",
+            self.used_label(),
+            self.budget_label(),
+            self.unit_suffix(),
+            (self.ratio() * 100.0).round() as u64
+        )
+    }
+
+    fn used_label(&self) -> String {
+        match self.format {
+            MeterFormat::Tokens => format_token_count(self.used.max(0.0).round() as u64),
+            MeterFormat::Currency => format_currency(self.used.max(0.0)),
+        }
+    }
+
+    fn budget_label(&self) -> String {
+        match self.format {
+            MeterFormat::Tokens => format_token_count(self.budget.max(0.0).round() as u64),
+            MeterFormat::Currency => format_currency(self.budget.max(0.0)),
+        }
+    }
+
+    fn unit_suffix(&self) -> &'static str {
+        match self.format {
+            MeterFormat::Tokens => " tok",
+            MeterFormat::Currency => "",
+        }
+    }
+}
+
+impl Widget for TokenMeter<'_> {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        if area.is_empty() {
+            return;
+        }
+
+        let mut gauge_area = area;
+        if area.height > 1 {
+            let chunks = Layout::default()
+                .direction(Direction::Vertical)
+                .constraints([Constraint::Length(1), Constraint::Min(1)])
+                .split(area);
+            Paragraph::new(self.title_line()).render(chunks[0], buf);
+            gauge_area = chunks[1];
+        }
+
+        Gauge::default()
+            .ratio(self.clamped_ratio())
+            .label(self.display_label())
+            .gauge_style(
+                Style::default()
+                    .fg(gradient_color(self.ratio()))
+                    .add_modifier(Modifier::BOLD),
+            )
+            .style(Style::default().fg(Color::DarkGray))
+            .use_unicode(true)
+            .render(gauge_area, buf);
+    }
+}
+
+pub(crate) fn budget_ratio(used: f64, budget: f64) -> f64 {
+    if budget <= 0.0 {
+        0.0
+    } else {
+        used / budget
+    }
+}
+
+pub(crate) fn budget_state(used: f64, budget: f64) -> BudgetState {
+    if budget <= 0.0 {
+        BudgetState::Unconfigured
+    } else if used / budget >= 1.0 {
+        BudgetState::OverBudget
+    } else if used / budget >= WARNING_THRESHOLD {
+        BudgetState::Warning
+    } else {
+        BudgetState::Normal
+    }
+}
+
+pub(crate) fn gradient_color(ratio: f64) -> Color {
+    const GREEN: (u8, u8, u8) = (34, 197, 94);
+    const YELLOW: (u8, u8, u8) = (234, 179, 8);
+    const RED: (u8, u8, u8) = (239, 68, 68);
+
+    let clamped = ratio.clamp(0.0, 1.0);
+    if clamped <= WARNING_THRESHOLD {
+        interpolate_rgb(GREEN, YELLOW, clamped / WARNING_THRESHOLD)
+    } else {
+        interpolate_rgb(
+            YELLOW,
+            RED,
+            (clamped - WARNING_THRESHOLD) / (1.0 - WARNING_THRESHOLD),
+        )
+    }
+}
+
+pub(crate) fn format_currency(value: f64) -> String {
+    format!("${value:.2}")
+}
+
+pub(crate) fn format_token_count(value: u64) -> String {
+    let digits = value.to_string();
+    let mut formatted = String::with_capacity(digits.len() + digits.len() / 3);
+
+    for (index, ch) in digits.chars().rev().enumerate() {
+        if index != 0 && index % 3 == 0 {
+            formatted.push(',');
+        }
+        formatted.push(ch);
+    }
+
+    formatted.chars().rev().collect()
+}
+
+fn interpolate_rgb(from: (u8, u8, u8), to: (u8, u8, u8), ratio: f64) -> Color {
+    let ratio = ratio.clamp(0.0, 1.0);
+    let channel = |start: u8, end: u8| -> u8 {
+        (f64::from(start) + (f64::from(end) - f64::from(start)) * ratio).round() as u8
+    };
+
+    Color::Rgb(
+        channel(from.0, to.0),
+        channel(from.1, to.1),
+        channel(from.2, to.2),
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use ratatui::{buffer::Buffer, layout::Rect, style::Color, widgets::Widget};
+
+    use super::{gradient_color, BudgetState, TokenMeter};
+
+    #[test]
+    fn warning_state_starts_at_eighty_percent() {
+        let meter = TokenMeter::tokens("Token Budget", 80, 100);
+
+        assert_eq!(meter.state(), BudgetState::Warning);
+    }
+
+    #[test]
+    fn gradient_runs_from_green_to_yellow_to_red() {
+        assert_eq!(gradient_color(0.0), Color::Rgb(34, 197, 94));
+        assert_eq!(gradient_color(0.8), Color::Rgb(234, 179, 8));
+        assert_eq!(gradient_color(1.0), Color::Rgb(239, 68, 68));
+    }
+
+    #[test]
+    fn token_meter_renders_compact_usage_label() {
+        let meter = TokenMeter::tokens("Token Budget", 4_000, 10_000);
+        let area = Rect::new(0, 0, 48, 2);
+        let mut buffer = Buffer::empty(area);
+
+        meter.render(area, &mut buffer);
+
+        let rendered = buffer
+            .content()
+            .chunks(area.width as usize)
+            .flat_map(|row| row.iter().map(|cell| cell.symbol()))
+            .collect::<String>();
+
+        assert!(rendered.contains("4,000 / 10,000 tok (40%)"));
+    }
+}

ecc2/src/worktree/mod.rs

@@ -1,5 +1,5 @@
 use anyhow::{Context, Result};
-use std::path::PathBuf;
+use std::path::Path;
 use std::process::Command;
 
 use crate::config::Config;
@@ -7,16 +7,27 @@ use crate::session::WorktreeInfo;
 
 /// Create a new git worktree for an agent session.
 pub fn create_for_session(session_id: &str, cfg: &Config) -> Result<WorktreeInfo> {
+    let repo_root = std::env::current_dir().context("Failed to resolve repository root")?;
+    create_for_session_in_repo(session_id, cfg, &repo_root)
+}
+
+pub(crate) fn create_for_session_in_repo(
+    session_id: &str,
+    cfg: &Config,
+    repo_root: &Path,
+) -> Result<WorktreeInfo> {
     let branch = format!("ecc/{session_id}");
     let path = cfg.worktree_root.join(session_id);
 
     // Get current branch as base
-    let base = get_current_branch()?;
+    let base = get_current_branch(repo_root)?;
 
     std::fs::create_dir_all(&cfg.worktree_root)
         .context("Failed to create worktree root directory")?;
 
     let output = Command::new("git")
+        .arg("-C")
+        .arg(repo_root)
         .args(["worktree", "add", "-b", &branch])
         .arg(&path)
         .arg("HEAD")
@@ -28,7 +39,11 @@ pub fn create_for_session(session_id: &str, cfg: &Config) -> Result<WorktreeInfo
         anyhow::bail!("git worktree add failed: {stderr}");
     }
 
-    tracing::info!("Created worktree at {} on branch {}", path.display(), branch);
+    tracing::info!(
+        "Created worktree at {} on branch {}",
+        path.display(),
+        branch
+    );
 
     Ok(WorktreeInfo {
         path,
@@ -38,8 +53,10 @@ pub fn create_for_session(session_id: &str, cfg: &Config) -> Result<WorktreeInfo
 }
 
 /// Remove a worktree and its branch.
-pub fn remove(path: &PathBuf) -> Result<()> {
+pub fn remove(path: &Path) -> Result<()> {
     let output = Command::new("git")
+        .arg("-C")
+        .arg(path)
         .args(["worktree", "remove", "--force"])
         .arg(path)
         .output()
@@ -70,8 +87,10 @@ pub fn list() -> Result<Vec<String>> {
     Ok(worktrees)
 }
 
-fn get_current_branch() -> Result<String> {
+fn get_current_branch(repo_root: &Path) -> Result<String> {
     let output = Command::new("git")
+        .arg("-C")
+        .arg(repo_root)
         .args(["rev-parse", "--abbrev-ref", "HEAD"])
         .output()
         .context("Failed to get current branch")?;