✨ Add Iris Companion for ambient session awareness

Introduce a new companion module that transforms Studio into an
always-aware development assistant. The companion tracks:

- Branch memory: Persists context across sessions including last focus,
  notes, and commit counts. Shows welcome messages when returning.
- Session state: Files touched, commits made, and session duration.
- Live file watching: Monitors repository changes with debouncing and
  gitignore filtering using the notify crate.

Data persists to ~/.iris/repos/{repo-hash}/ with atomic writes for
safety. Companion events integrate with Studio's event system and
update the UI in real-time.

Dependencies: notify, notify-debouncer-full, ignore

Author: hyperb1iss

Cargo.lock

@@ -34,8 +34,11 @@ crossterm = "0.28.1"
 dirs = "6.0.0"
 futures = "0.3.30"
 git2 = "0.20.1"
+ignore = "0.4"
 indicatif = "0.17.8"
 log = "0.4.27"
+notify = "8.0"
+notify-debouncer-full = "0.5"
 lru = "0.12"
 once_cell = "1.21.3"
 parking_lot = "0.12.1"

Cargo.toml

@@ -0,0 +1,119 @@
+//! Branch memory for Iris Companion
+//!
+//! Remembers context per branch across sessions.
+
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use std::path::PathBuf;
+
+/// Focus state - where the user was last working
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct FileFocus {
+    /// Path to the focused file
+    pub path: PathBuf,
+    /// Line number in the file
+    pub line: usize,
+    /// When this focus was recorded
+    pub timestamp: DateTime<Utc>,
+}
+
+impl FileFocus {
+    /// Create a new file focus
+    pub fn new(path: PathBuf, line: usize) -> Self {
+        Self {
+            path,
+            line,
+            timestamp: Utc::now(),
+        }
+    }
+}
+
+/// Per-branch persistent memory
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BranchMemory {
+    /// Branch name
+    pub branch_name: String,
+    /// When this branch was first visited
+    pub created_at: DateTime<Utc>,
+    /// When this branch was last visited
+    pub last_visited: DateTime<Utc>,
+    /// Last focused file and line
+    pub last_focus: Option<FileFocus>,
+    /// User notes for this branch
+    pub notes: Vec<String>,
+    /// Number of sessions on this branch
+    pub session_count: u32,
+    /// Number of commits made on this branch (across sessions)
+    pub total_commits: u32,
+}
+
+impl BranchMemory {
+    /// Create new branch memory
+    pub fn new(branch_name: String) -> Self {
+        let now = Utc::now();
+        Self {
+            branch_name,
+            created_at: now,
+            last_visited: now,
+            last_focus: None,
+            notes: Vec::new(),
+            session_count: 1,
+            total_commits: 0,
+        }
+    }
+
+    /// Record a new session visit
+    pub fn record_visit(&mut self) {
+        self.last_visited = Utc::now();
+        self.session_count += 1;
+    }
+
+    /// Update last focus
+    pub fn set_focus(&mut self, path: PathBuf, line: usize) {
+        self.last_focus = Some(FileFocus::new(path, line));
+    }
+
+    /// Clear focus
+    pub fn clear_focus(&mut self) {
+        self.last_focus = None;
+    }
+
+    /// Add a note
+    pub fn add_note(&mut self, note: String) {
+        self.notes.push(note);
+    }
+
+    /// Record a commit
+    pub fn record_commit(&mut self) {
+        self.total_commits += 1;
+    }
+
+    /// Time since last visit
+    pub fn time_since_last_visit(&self) -> chrono::Duration {
+        Utc::now() - self.last_visited
+    }
+
+    /// Check if this is a returning visit (visited before more than 5 minutes ago)
+    pub fn is_returning_visit(&self) -> bool {
+        self.session_count > 1
+            && self.time_since_last_visit() > chrono::Duration::minutes(5)
+    }
+
+    /// Generate a welcome message if returning
+    pub fn welcome_message(&self) -> Option<String> {
+        if !self.is_returning_visit() {
+            return None;
+        }
+
+        let duration = self.time_since_last_visit();
+        let time_str = if duration.num_days() > 0 {
+            format!("{} days ago", duration.num_days())
+        } else if duration.num_hours() > 0 {
+            format!("{} hours ago", duration.num_hours())
+        } else {
+            format!("{} minutes ago", duration.num_minutes())
+        };
+
+        Some(format!("Welcome back to {}! Last here {}", self.branch_name, time_str))
+    }
+}

src/companion/branch_memory.rs

@@ -0,0 +1,131 @@
+//! Iris Companion - Ambient awareness for Git workflows
+//!
+//! Provides session tracking, branch memory, and live file watching
+//! to transform Studio into an always-aware development companion.
+
+mod branch_memory;
+mod session;
+mod storage;
+mod watcher;
+
+pub use branch_memory::{BranchMemory, FileFocus};
+pub use session::{FileActivity, SessionState};
+pub use storage::CompanionStorage;
+pub use watcher::{CompanionEvent, FileWatcherService};
+
+use anyhow::Result;
+use std::path::PathBuf;
+use std::sync::Arc;
+use tokio::sync::mpsc;
+
+/// Main companion service that coordinates all subsystems
+pub struct CompanionService {
+    /// Repository path being watched
+    repo_path: PathBuf,
+    /// Current session state
+    session: Arc<parking_lot::RwLock<SessionState>>,
+    /// Storage backend for persistence
+    storage: CompanionStorage,
+    /// File watcher service (optional - may fail to start)
+    watcher: Option<FileWatcherService>,
+    /// Channel for receiving companion events
+    event_rx: mpsc::UnboundedReceiver<CompanionEvent>,
+    /// Channel sender (held to keep channel alive)
+    _event_tx: mpsc::UnboundedSender<CompanionEvent>,
+}
+
+impl CompanionService {
+    /// Create a new companion service for the given repository
+    pub fn new(repo_path: PathBuf, branch: &str) -> Result<Self> {
+        let (event_tx, event_rx) = mpsc::unbounded_channel();
+
+        // Initialize storage
+        let storage = CompanionStorage::new(&repo_path)?;
+
+        // Try to load existing session or create new one
+        let session = storage
+            .load_session()?
+            .filter(|s| s.branch == branch) // Only restore if same branch
+            .unwrap_or_else(|| SessionState::new(repo_path.clone(), branch.to_owned()));
+
+        let session = Arc::new(parking_lot::RwLock::new(session));
+
+        // Try to start file watcher (non-fatal if it fails)
+        let watcher = match FileWatcherService::new(&repo_path, event_tx.clone()) {
+            Ok(w) => {
+                tracing::info!("Companion file watcher started");
+                Some(w)
+            }
+            Err(e) => {
+                tracing::warn!("Failed to start file watcher: {}. Companion will run without live updates.", e);
+                None
+            }
+        };
+
+        Ok(Self {
+            repo_path,
+            session,
+            storage,
+            watcher,
+            event_rx,
+            _event_tx: event_tx,
+        })
+    }
+
+    /// Get the current session state
+    pub fn session(&self) -> &Arc<parking_lot::RwLock<SessionState>> {
+        &self.session
+    }
+
+    /// Load branch memory for the given branch
+    pub fn load_branch_memory(&self, branch: &str) -> Result<Option<BranchMemory>> {
+        self.storage.load_branch_memory(branch)
+    }
+
+    /// Save branch memory
+    pub fn save_branch_memory(&self, memory: &BranchMemory) -> Result<()> {
+        self.storage.save_branch_memory(memory)
+    }
+
+    /// Save current session state
+    pub fn save_session(&self) -> Result<()> {
+        let session = self.session.read();
+        self.storage.save_session(&session)
+    }
+
+    /// Record a file touch (opened/modified)
+    pub fn touch_file(&self, path: PathBuf) {
+        let mut session = self.session.write();
+        session.touch_file(path);
+    }
+
+    /// Record a commit was made
+    pub fn record_commit(&self, hash: String) {
+        let mut session = self.session.write();
+        session.record_commit(hash);
+    }
+
+    /// Try to receive the next companion event (non-blocking)
+    pub fn try_recv_event(&mut self) -> Option<CompanionEvent> {
+        self.event_rx.try_recv().ok()
+    }
+
+    /// Check if file watcher is active
+    pub fn has_watcher(&self) -> bool {
+        self.watcher.is_some()
+    }
+
+    /// Get repository path
+    pub fn repo_path(&self) -> &PathBuf {
+        &self.repo_path
+    }
+}
+
+impl Drop for CompanionService {
+    fn drop(&mut self) {
+        // Try to save session on shutdown
+        if let Err(e) = self.save_session() {
+            tracing::warn!("Failed to save session on shutdown: {}", e);
+        }
+    }
+}

src/companion/mod.rs

@@ -0,0 +1,123 @@
+//! Session state tracking for Iris Companion
+//!
+//! Tracks files touched, time elapsed, and commits made during a session.
+
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::path::PathBuf;
+use uuid::Uuid;
+
+/// Activity tracking for a single file
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct FileActivity {
+    /// Path to the file
+    pub path: PathBuf,
+    /// When this file was first touched in the session
+    pub first_touched: DateTime<Utc>,
+    /// When this file was last touched
+    pub last_touched: DateTime<Utc>,
+    /// Number of times this file was touched
+    pub touch_count: u32,
+}
+
+impl FileActivity {
+    /// Create a new file activity record
+    pub fn new(path: PathBuf) -> Self {
+        let now = Utc::now();
+        Self {
+            path,
+            first_touched: now,
+            last_touched: now,
+            touch_count: 1,
+        }
+    }
+
+    /// Record another touch
+    pub fn touch(&mut self) {
+        self.last_touched = Utc::now();
+        self.touch_count += 1;
+    }
+}
+
+/// Session state for the current Studio session
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SessionState {
+    /// Unique session identifier
+    pub session_id: Uuid,
+    /// Repository path
+    pub repo_path: PathBuf,
+    /// Current branch name
+    pub branch: String,
+    /// When the session started
+    pub started_at: DateTime<Utc>,
+    /// Last activity timestamp
+    pub last_activity: DateTime<Utc>,
+    /// Files touched during this session
+    pub files_touched: HashMap<PathBuf, FileActivity>,
+    /// Commits made during this session (hashes)
+    pub commits_made: Vec<String>,
+}
+
+impl SessionState {
+    /// Create a new session
+    pub fn new(repo_path: PathBuf, branch: String) -> Self {
+        let now = Utc::now();
+        Self {
+            session_id: Uuid::new_v4(),
+            repo_path,
+            branch,
+            started_at: now,
+            last_activity: now,
+            files_touched: HashMap::new(),
+            commits_made: Vec::new(),
+        }
+    }
+
+    /// Record a file touch
+    pub fn touch_file(&mut self, path: PathBuf) {
+        self.last_activity = Utc::now();
+        self.files_touched
+            .entry(path.clone())
+            .and_modify(FileActivity::touch)
+            .or_insert_with(|| FileActivity::new(path));
+    }
+
+    /// Record a commit
+    pub fn record_commit(&mut self, hash: String) {
+        self.last_activity = Utc::now();
+        self.commits_made.push(hash);
+    }
+
+    /// Get session duration
+    pub fn duration(&self) -> chrono::Duration {
+        Utc::now() - self.started_at
+    }
+
+    /// Get number of files touched
+    pub fn files_count(&self) -> usize {
+        self.files_touched.len()
+    }
+
+    /// Get files ordered by most recently touched
+    pub fn recent_files(&self) -> Vec<&FileActivity> {
+        let mut files: Vec<_> = self.files_touched.values().collect();
+        files.sort_by(|a, b| b.last_touched.cmp(&a.last_touched));
+        files
+    }
+
+    /// Get time since last commit (if any)
+    pub fn time_since_last_commit(&self) -> Option<chrono::Duration> {
+        if self.commits_made.is_empty() {
+            None
+        } else {
+            Some(Utc::now() - self.last_activity)
+        }
+    }
+
+    /// Update branch (for branch switches)
+    pub fn set_branch(&mut self, branch: String) {
+        self.branch = branch;
+        self.last_activity = Utc::now();
+    }
+}