handoff-mcp-server 0.6.2 → 0.7.1

package/Cargo.lock

@@ -144,7 +144,7 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.6.2"
+version = "0.7.1"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.6.2"
+version = "0.7.1"
 edition = "2021"
 description = "MCP server that gives AI coding agents persistent memory across sessions"
 license = "MIT"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-mcp-server",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "MCP server that gives AI coding agents persistent memory across sessions",
   "license": "MIT",
   "author": "AlphaElements <66808803+alphaelements@users.noreply.github.com>",

package/src/mcp/handlers/dashboard.rs

@@ -6,7 +6,7 @@ use serde_json::Value;
 use crate::storage::config::read_config;
 use crate::storage::expand_tilde;
 use crate::storage::referrals::read_referral_summaries;
-use crate::storage::sessions::{read_active_sessions, read_open_sessions};
+use crate::storage::sessions::{read_active_sessions, read_open_sessions, read_paused_sessions};
 use crate::storage::tasks::build_task_index;
 
 pub fn handle(arguments: &Value) -> Result<String> {
@@ -73,6 +73,9 @@ fn collect_project_info(project_path: &Path) -> Result<Value> {
     let sessions_dir = handoff_dir.join("sessions");
     let mut sessions = read_open_sessions(&sessions_dir)?;
     sessions.extend(read_active_sessions(&sessions_dir)?);
+    let paused = read_paused_sessions(&sessions_dir)?;
+    let paused_count = paused.len() as u32;
+    sessions.extend(paused);
 
     let (_, summary) =
         build_task_index(&handoff_dir.join("tasks"), config.settings.done_task_limit)?;
@@ -105,5 +108,6 @@ fn collect_project_info(project_path: &Path) -> Result<Value> {
         "blocked_tasks": blocked_tasks,
         "blockers": blockers,
         "unread_referrals": unread_referrals,
+        "paused_sessions": paused_count,
     }))
 }

package/src/mcp/handlers/load_context.rs

@@ -5,7 +5,8 @@ use super::resolve_project_dir;
 use crate::storage::config::read_config;
 use crate::storage::referrals::read_referral_summaries;
 use crate::storage::sessions::{
-    activate_open_sessions, activate_session_by_id, read_open_sessions,
+    activate_open_sessions, activate_session_by_id, read_active_sessions, read_open_sessions,
+    read_paused_sessions, resume_paused_session_by_id,
 };
 use crate::storage::tasks::build_task_index;
 use crate::storage::{ensure_handoff_exists, handoff_dir};
@@ -38,13 +39,50 @@ pub fn handle(arguments: &Value) -> Result<String> {
 
     let target_session_id = arguments.get("session_id").and_then(|v| v.as_str());
 
+    let active_sessions = read_active_sessions(&sessions_dir)?;
     let sessions = read_open_sessions(&sessions_dir)?;
+    let paused_sessions = read_paused_sessions(&sessions_dir)?;
 
     let selected_session = if let Some(sid) = target_session_id {
-        activate_session_by_id(&sessions_dir, sid)?;
-        sessions
-            .into_iter()
-            .find(|s| s.id.as_deref().is_some_and(|id| id == sid))
+        let already_active = active_sessions
+            .iter()
+            .any(|s| s.id.as_deref().is_some_and(|id| id == sid));
+        if already_active {
+            active_sessions
+                .into_iter()
+                .find(|s| s.id.as_deref().is_some_and(|id| id == sid))
+        } else if !active_sessions.is_empty() {
+            let active_ids: Vec<String> = active_sessions
+                .iter()
+                .filter_map(|s| s.id.clone())
+                .collect();
+            anyhow::bail!(
+                "Cannot activate session '{sid}': another session is already active ({}).\n\
+                 Use save_context with close_session_id or pause_session_id to \
+                 close/pause the active session first.",
+                active_ids.join(", ")
+            );
+        } else if activate_session_by_id(&sessions_dir, sid)?.is_some() {
+            sessions
+                .into_iter()
+                .find(|s| s.id.as_deref().is_some_and(|id| id == sid))
+        } else if resume_paused_session_by_id(&sessions_dir, sid)?.is_some() {
+            paused_sessions
+                .into_iter()
+                .find(|s| s.id.as_deref().is_some_and(|id| id == sid))
+        } else {
+            None
+        }
+    } else if !active_sessions.is_empty() {
+        active_sessions.into_iter().last()
+    } else if sessions.len() > 1 {
+        let open_ids: Vec<String> = sessions.iter().filter_map(|s| s.id.clone()).collect();
+        anyhow::bail!(
+            "Multiple open sessions found ({}).\n\
+             Specify session_id to choose one, or use save_context to \
+             close/pause the others first.",
+            open_ids.join(", ")
+        );
     } else {
         activate_open_sessions(&sessions_dir)?;
         sessions.into_iter().last()
@@ -126,5 +164,21 @@ pub fn handle(arguments: &Value) -> Result<String> {
         result["referrals"] = serde_json::to_value(&open_referrals)?;
     }
 
+    let current_paused = read_paused_sessions(&sessions_dir)?;
+    if !current_paused.is_empty() {
+        let summaries: Vec<Value> = current_paused
+            .iter()
+            .map(|s| {
+                serde_json::json!({
+                    "id": s.id,
+                    "summary": s.summary,
+                    "ended_at": s.ended_at,
+                    "branch": s.branch,
+                })
+            })
+            .collect();
+        result["paused_sessions"] = serde_json::json!(summaries);
+    }
+
     serde_json::to_string_pretty(&result).context("Failed to serialize context")
 }

package/src/mcp/handlers/save_context.rs

@@ -10,7 +10,8 @@ use crate::storage::ensure_handoff_exists;
 use crate::storage::git::capture_git_state;
 use crate::storage::sessions::{
     close_active_sessions, close_open_sessions, close_session_by_id, enforce_history_limit,
-    generate_session_id, write_open_session, SessionData,
+    generate_session_id, pause_active_sessions, pause_session_by_id, read_active_sessions,
+    write_open_session, SessionData,
 };
 
 pub fn handle(arguments: &Value) -> Result<String> {
@@ -26,6 +27,20 @@ pub fn handle(arguments: &Value) -> Result<String> {
         .ok_or_else(|| anyhow::anyhow!("'summary' is required"))?;
 
     let close_id = arguments.get("close_session_id").and_then(|v| v.as_str());
+    let pause_id = arguments.get("pause_session_id").and_then(|v| v.as_str());
+    let pause_all = arguments
+        .get("pause_active")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false);
+
+    let mut total_paused = 0usize;
+    if let Some(id) = pause_id {
+        if pause_session_by_id(&sessions_dir, id)?.is_some() {
+            total_paused = 1;
+        }
+    } else if pause_all {
+        total_paused = pause_active_sessions(&sessions_dir)?.len();
+    }
 
     let total_closed = if let Some(id) = close_id {
         let closed = close_session_by_id(&sessions_dir, id)?;
@@ -34,7 +49,20 @@ pub fn handle(arguments: &Value) -> Result<String> {
         } else {
             0
         }
+    } else if pause_id.is_some() || pause_all {
+        let closed_open = close_open_sessions(&sessions_dir)?;
+        closed_open.len()
     } else {
+        let active = read_active_sessions(&sessions_dir)?;
+        if active.len() > 1 {
+            let active_ids: Vec<String> = active.iter().filter_map(|s| s.id.clone()).collect();
+            anyhow::bail!(
+                "Multiple active sessions found ({}).\n\
+                 Use close_session_id or pause_session_id to specify which to \
+                 close/pause before saving a new session.",
+                active_ids.join(", ")
+            );
+        }
         let closed_active = close_active_sessions(&sessions_dir)?;
         let closed_open = close_open_sessions(&sessions_dir)?;
         closed_active.len() + closed_open.len()
@@ -81,13 +109,23 @@ pub fn handle(arguments: &Value) -> Result<String> {
             .unwrap_or_default()
     );
 
+    if total_paused > 0 {
+        msg.push_str(&format!("\nPaused {} session(s)", total_paused));
+    }
+    if let Some(id) = pause_id {
+        if total_paused == 0 {
+            msg.push_str(&format!(
+                "\nWarning: pause_session_id '{id}' not found among active sessions"
+            ));
+        }
+    }
     if total_closed > 0 {
         msg.push_str(&format!("\nClosed {} previous session(s)", total_closed));
     }
     if let Some(id) = close_id {
         if total_closed == 0 {
             msg.push_str(&format!(
-                "\nWarning: close_session_id '{id}' not found among active/open sessions"
+                "\nWarning: close_session_id '{id}' not found among active/open/paused sessions"
             ));
         }
     }

package/src/mcp/resources.rs

@@ -2,7 +2,7 @@ use anyhow::{Context, Result};
 use serde_json::{json, Value};
 
 use crate::storage::config::read_config;
-use crate::storage::sessions::{read_active_sessions, read_open_sessions};
+use crate::storage::sessions::{read_active_sessions, read_open_sessions, read_paused_sessions};
 use crate::storage::{ensure_handoff_exists, handoff_dir};
 
 pub fn handle_resource_read(uri: &str) -> Result<Value> {
@@ -26,6 +26,7 @@ fn read_sessions_resource(handoff: &std::path::Path) -> Result<Value> {
     let sessions_dir = handoff.join("sessions");
     let mut sessions = read_open_sessions(&sessions_dir)?;
     sessions.extend(read_active_sessions(&sessions_dir)?);
+    sessions.extend(read_paused_sessions(&sessions_dir)?);
 
     let contents: Vec<Value> = sessions
         .iter()

package/src/mcp/tools.rs

@@ -28,7 +28,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
         },
         ToolDefinition {
             name: "handoff_load_context".to_string(),
-            description: "Load handoff context for the current project. Call at session start to resume work.".to_string(),
+            description: "Load handoff context for the current project. Call at session start to resume work. Can also resume a paused session by ID.".to_string(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
@@ -38,7 +38,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     },
                     "session_id": {
                         "type": "string",
-                        "description": "Session ID to activate and load. If omitted, activates all open sessions and returns the latest."
+                        "description": "Session ID to activate and load. Searches open sessions first, then paused sessions. If omitted, activates all open sessions and returns the latest."
                     }
                 }
             }),
@@ -59,7 +59,15 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     },
                     "close_session_id": {
                         "type": "string",
-                        "description": "Session ID to close. If omitted, all active and open sessions are closed (default behavior)."
+                        "description": "Session ID to close. If omitted (and no pause options set), all active and open sessions are closed."
+                    },
+                    "pause_session_id": {
+                        "type": "string",
+                        "description": "Session ID to pause instead of close. The paused session can be resumed later via load_context with the same session_id. Use this when switching to different work temporarily."
+                    },
+                    "pause_active": {
+                        "type": "boolean",
+                        "description": "If true, pause all active sessions instead of closing them. Cannot be combined with close_session_id."
                     },
                     "decisions": {
                         "type": "array",

package/src/storage/sessions.rs

@@ -258,11 +258,37 @@ pub fn close_open_sessions(sessions_dir: &Path) -> Result<Vec<PathBuf>> {
 }
 
 pub fn close_session_by_id(sessions_dir: &Path, session_id: &str) -> Result<Option<PathBuf>> {
-    // Try active first, then open
+    // Try active first, then open, then paused
     if let Some(path) = transition_session_by_id(sessions_dir, session_id, "active", "closed")? {
         return Ok(Some(path));
     }
-    transition_session_by_id(sessions_dir, session_id, "open", "closed")
+    if let Some(path) = transition_session_by_id(sessions_dir, session_id, "open", "closed")? {
+        return Ok(Some(path));
+    }
+    transition_session_by_id(sessions_dir, session_id, "paused", "closed")
+}
+
+pub fn pause_active_sessions(sessions_dir: &Path) -> Result<Vec<PathBuf>> {
+    transition_sessions(sessions_dir, "active", "paused")
+}
+
+pub fn pause_session_by_id(sessions_dir: &Path, session_id: &str) -> Result<Option<PathBuf>> {
+    transition_session_by_id(sessions_dir, session_id, "active", "paused")
+}
+
+pub fn resume_paused_session_by_id(
+    sessions_dir: &Path,
+    session_id: &str,
+) -> Result<Option<PathBuf>> {
+    transition_session_by_id(sessions_dir, session_id, "paused", "active")
+}
+
+pub fn read_paused_sessions(sessions_dir: &Path) -> Result<Vec<SessionData>> {
+    read_sessions_by_status(sessions_dir, "paused")
+}
+
+pub fn close_paused_sessions(sessions_dir: &Path) -> Result<Vec<PathBuf>> {
+    transition_sessions(sessions_dir, "paused", "closed")
 }
 
 pub fn enforce_history_limit(sessions_dir: &Path, limit: u32) -> Result<u32> {

package/tests/storage_sessions.rs

@@ -357,3 +357,179 @@ fn close_session_by_id_nonexistent_returns_none() {
     let result = close_session_by_id(&sessions_dir, "s-nonexistent").unwrap();
     assert!(result.is_none());
 }
+
+#[test]
+fn pause_active_sessions_renames_to_paused() {
+    let dir = setup();
+    let sessions_dir = dir.path().join("sessions");
+    fs::create_dir_all(&sessions_dir).unwrap();
+
+    let s = make_session("working on feature", "2026-06-15T10:00:00Z");
+    write_open_session(&sessions_dir, &s).unwrap();
+    activate_open_sessions(&sessions_dir).unwrap();
+
+    let paused = pause_active_sessions(&sessions_dir).unwrap();
+    assert_eq!(paused.len(), 1);
+    assert!(paused[0].to_string_lossy().contains(".paused.json"));
+    assert!(paused[0].exists());
+
+    assert!(read_active_sessions(&sessions_dir).unwrap().is_empty());
+    let paused_sessions = read_paused_sessions(&sessions_dir).unwrap();
+    assert_eq!(paused_sessions.len(), 1);
+    assert_eq!(paused_sessions[0].summary, "working on feature");
+}
+
+#[test]
+fn pause_session_by_id_pauses_only_targeted() {
+    let dir = setup();
+    let sessions_dir = dir.path().join("sessions");
+    fs::create_dir_all(&sessions_dir).unwrap();
+
+    let s1 = make_session("session one", "2026-06-15T10:00:00Z");
+    let s2 = make_session("session two", "2026-06-15T11:00:00Z");
+    write_open_session(&sessions_dir, &s1).unwrap();
+    write_open_session(&sessions_dir, &s2).unwrap();
+    activate_open_sessions(&sessions_dir).unwrap();
+
+    let active = read_active_sessions(&sessions_dir).unwrap();
+    assert_eq!(active.len(), 2);
+    let target_id = active[0].id.as_ref().unwrap().clone();
+
+    let result = pause_session_by_id(&sessions_dir, &target_id).unwrap();
+    assert!(result.is_some());
+
+    let remaining_active = read_active_sessions(&sessions_dir).unwrap();
+    assert_eq!(remaining_active.len(), 1);
+
+    let paused = read_paused_sessions(&sessions_dir).unwrap();
+    assert_eq!(paused.len(), 1);
+    assert_eq!(paused[0].id.as_deref().unwrap(), target_id);
+}
+
+#[test]
+fn resume_paused_session_by_id_reactivates() {
+    let dir = setup();
+    let sessions_dir = dir.path().join("sessions");
+    fs::create_dir_all(&sessions_dir).unwrap();
+
+    let s = make_session("paused work", "2026-06-15T10:00:00Z");
+    write_open_session(&sessions_dir, &s).unwrap();
+    activate_open_sessions(&sessions_dir).unwrap();
+    pause_active_sessions(&sessions_dir).unwrap();
+
+    let paused = read_paused_sessions(&sessions_dir).unwrap();
+    assert_eq!(paused.len(), 1);
+    let sid = paused[0].id.as_ref().unwrap().clone();
+
+    let result = resume_paused_session_by_id(&sessions_dir, &sid).unwrap();
+    assert!(result.is_some());
+    assert!(result.unwrap().to_string_lossy().contains(".active.json"));
+
+    assert!(read_paused_sessions(&sessions_dir).unwrap().is_empty());
+    let active = read_active_sessions(&sessions_dir).unwrap();
+    assert_eq!(active.len(), 1);
+    assert_eq!(active[0].summary, "paused work");
+}
+
+#[test]
+fn close_session_by_id_closes_paused() {
+    let dir = setup();
+    let sessions_dir = dir.path().join("sessions");
+    fs::create_dir_all(&sessions_dir).unwrap();
+
+    let s = make_session("will close from paused", "2026-06-15T10:00:00Z");
+    write_open_session(&sessions_dir, &s).unwrap();
+    activate_open_sessions(&sessions_dir).unwrap();
+    pause_active_sessions(&sessions_dir).unwrap();
+
+    let paused = read_paused_sessions(&sessions_dir).unwrap();
+    let sid = paused[0].id.as_ref().unwrap().clone();
+
+    let result = close_session_by_id(&sessions_dir, &sid).unwrap();
+    assert!(result.is_some());
+    assert!(result.unwrap().to_string_lossy().contains(".closed.json"));
+
+    assert!(read_paused_sessions(&sessions_dir).unwrap().is_empty());
+}
+
+#[test]
+fn close_paused_sessions_closes_all() {
+    let dir = setup();
+    let sessions_dir = dir.path().join("sessions");
+    fs::create_dir_all(&sessions_dir).unwrap();
+
+    let s1 = make_session("paused one", "2026-06-15T10:00:00Z");
+    let s2 = make_session("paused two", "2026-06-15T11:00:00Z");
+    write_open_session(&sessions_dir, &s1).unwrap();
+    write_open_session(&sessions_dir, &s2).unwrap();
+    activate_open_sessions(&sessions_dir).unwrap();
+    pause_active_sessions(&sessions_dir).unwrap();
+
+    assert_eq!(read_paused_sessions(&sessions_dir).unwrap().len(), 2);
+
+    let closed = close_paused_sessions(&sessions_dir).unwrap();
+    assert_eq!(closed.len(), 2);
+    assert!(read_paused_sessions(&sessions_dir).unwrap().is_empty());
+}
+
+#[test]
+fn full_lifecycle_with_pause_and_resume() {
+    let dir = setup();
+    let sessions_dir = dir.path().join("sessions");
+    fs::create_dir_all(&sessions_dir).unwrap();
+
+    let s1 = make_session("feature work", "2026-06-15T10:00:00Z");
+    write_open_session(&sessions_dir, &s1).unwrap();
+    activate_open_sessions(&sessions_dir).unwrap();
+
+    let active = read_active_sessions(&sessions_dir).unwrap();
+    assert_eq!(active.len(), 1);
+    let s1_id = active[0].id.as_ref().unwrap().clone();
+
+    pause_session_by_id(&sessions_dir, &s1_id).unwrap();
+    assert!(read_active_sessions(&sessions_dir).unwrap().is_empty());
+    assert_eq!(read_paused_sessions(&sessions_dir).unwrap().len(), 1);
+
+    let s2 = make_session("urgent fix", "2026-06-15T12:00:00Z");
+    write_open_session(&sessions_dir, &s2).unwrap();
+    activate_open_sessions(&sessions_dir).unwrap();
+
+    let active2 = read_active_sessions(&sessions_dir).unwrap();
+    assert_eq!(active2.len(), 1);
+    assert_eq!(active2[0].summary, "urgent fix");
+    assert_eq!(read_paused_sessions(&sessions_dir).unwrap().len(), 1);
+
+    close_active_sessions(&sessions_dir).unwrap();
+
+    resume_paused_session_by_id(&sessions_dir, &s1_id).unwrap();
+    let active3 = read_active_sessions(&sessions_dir).unwrap();
+    assert_eq!(active3.len(), 1);
+    assert_eq!(active3[0].summary, "feature work");
+    assert!(read_paused_sessions(&sessions_dir).unwrap().is_empty());
+}
+
+#[test]
+fn enforce_history_limit_ignores_paused() {
+    let dir = setup();
+    let sessions_dir = dir.path().join("sessions");
+    fs::create_dir_all(&sessions_dir).unwrap();
+
+    for i in 1..=3 {
+        let name = format!("20260610-{i:06}-s{i}.closed.json");
+        fs::write(
+            sessions_dir.join(&name),
+            format!(r#"{{"version":2,"summary":"closed {i}"}}"#),
+        )
+        .unwrap();
+    }
+
+    let s = make_session("paused session", "2026-06-15T10:00:00Z");
+    write_open_session(&sessions_dir, &s).unwrap();
+    activate_open_sessions(&sessions_dir).unwrap();
+    pause_active_sessions(&sessions_dir).unwrap();
+
+    enforce_history_limit(&sessions_dir, 2).unwrap();
+
+    let paused = read_paused_sessions(&sessions_dir).unwrap();
+    assert_eq!(paused.len(), 1, "paused sessions should not be removed");
+}

package/tests/tool_sessions.rs

@@ -949,3 +949,362 @@ fn save_context_warns_on_unknown_close_session_id() {
         "should warn about unknown close_session_id: {text}"
     );
 }
+
+// --- pause/resume session tests ---
+
+#[test]
+fn save_context_with_pause_session_id() {
+    let dir = setup_project();
+    let pd = dir.path().to_string_lossy().to_string();
+
+    call_tool(
+        "handoff_save_context",
+        json!({ "project_dir": &pd, "summary": "session one" }),
+    );
+
+    let resp = call_tool("handoff_load_context", json!({ "project_dir": &pd }));
+    let text = get_text(&resp);
+    let parsed: Value = serde_json::from_str(&text).unwrap();
+    let session_id = parsed["session_id"].as_str().unwrap().to_string();
+
+    let resp = call_tool(
+        "handoff_save_context",
+        json!({
+            "project_dir": &pd,
+            "summary": "session two (switching work)",
+            "pause_session_id": session_id
+        }),
+    );
+
+    let text = get_text(&resp);
+    assert!(!is_error(&resp), "error: {text}");
+    assert!(
+        text.contains("Paused 1 session(s)"),
+        "should report paused: {text}"
+    );
+
+    let sessions_dir = dir.path().join(".handoff/sessions");
+    let paused: Vec<_> = std::fs::read_dir(&sessions_dir)
+        .unwrap()
+        .filter_map(|e| e.ok())
+        .filter(|e| e.file_name().to_string_lossy().ends_with(".paused.json"))
+        .collect();
+    assert_eq!(paused.len(), 1, "should have 1 paused session");
+}
+
+#[test]
+fn save_context_with_pause_active() {
+    let dir = setup_project();
+    let pd = dir.path().to_string_lossy().to_string();
+
+    call_tool(
+        "handoff_save_context",
+        json!({ "project_dir": &pd, "summary": "session one" }),
+    );
+    call_tool("handoff_load_context", json!({ "project_dir": &pd }));
+
+    let resp = call_tool(
+        "handoff_save_context",
+        json!({
+            "project_dir": &pd,
+            "summary": "session two",
+            "pause_active": true
+        }),
+    );
+
+    let text = get_text(&resp);
+    assert!(!is_error(&resp), "error: {text}");
+    assert!(
+        text.contains("Paused 1 session(s)"),
+        "should report paused: {text}"
+    );
+}
+
+#[test]
+fn load_context_resumes_paused_session() {
+    let dir = setup_project();
+    let pd = dir.path().to_string_lossy().to_string();
+
+    call_tool(
+        "handoff_save_context",
+        json!({
+            "project_dir": &pd,
+            "summary": "original work",
+            "handoff_notes": [{ "note": "Continue feature X", "category": "suggestion" }]
+        }),
+    );
+
+    let resp = call_tool("handoff_load_context", json!({ "project_dir": &pd }));
+    let text = get_text(&resp);
+    let parsed: Value = serde_json::from_str(&text).unwrap();
+    let original_sid = parsed["session_id"].as_str().unwrap().to_string();
+
+    call_tool(
+        "handoff_save_context",
+        json!({
+            "project_dir": &pd,
+            "summary": "switching to urgent work",
+            "pause_session_id": &original_sid
+        }),
+    );
+
+    let resp = call_tool(
+        "handoff_load_context",
+        json!({ "project_dir": &pd, "session_id": &original_sid }),
+    );
+    let text = get_text(&resp);
+    let parsed: Value = serde_json::from_str(&text).unwrap();
+
+    assert_eq!(
+        parsed["session_id"].as_str().unwrap(),
+        original_sid,
+        "should resume the paused session"
+    );
+    assert!(
+        parsed["last_session"]["summary"]
+            .as_str()
+            .unwrap()
+            .contains("original work"),
+        "should load the original session data"
+    );
+}
+
+#[test]
+fn load_context_shows_paused_sessions() {
+    let dir = setup_project();
+    let pd = dir.path().to_string_lossy().to_string();
+
+    call_tool(
+        "handoff_save_context",
+        json!({ "project_dir": &pd, "summary": "work A" }),
+    );
+    call_tool("handoff_load_context", json!({ "project_dir": &pd }));
+
+    call_tool(
+        "handoff_save_context",
+        json!({
+            "project_dir": &pd,
+            "summary": "work B",
+            "pause_active": true
+        }),
+    );
+
+    let resp = call_tool("handoff_load_context", json!({ "project_dir": &pd }));
+    let text = get_text(&resp);
+    let parsed: Value = serde_json::from_str(&text).unwrap();
+
+    let paused = parsed["paused_sessions"]
+        .as_array()
+        .expect("should have paused_sessions");
+    assert_eq!(paused.len(), 1);
+    assert_eq!(paused[0]["summary"], "work A");
+}
+
+#[test]
+fn save_context_pause_unknown_id_warns() {
+    let dir = setup_project();
+    let pd = dir.path().to_string_lossy().to_string();
+
+    let resp = call_tool(
+        "handoff_save_context",
+        json!({
+            "project_dir": &pd,
+            "summary": "new session",
+            "pause_session_id": "s-99999999-999999-999999"
+        }),
+    );
+
+    let text = get_text(&resp);
+    assert!(
+        text.contains("not found"),
+        "should warn about unknown pause_session_id: {text}"
+    );
+}
+
+#[test]
+fn full_pause_resume_lifecycle() {
+    let dir = setup_project();
+    let pd = dir.path().to_string_lossy().to_string();
+
+    call_tool(
+        "handoff_save_context",
+        json!({
+            "project_dir": &pd,
+            "summary": "feature work"
+        }),
+    );
+    let resp = call_tool("handoff_load_context", json!({ "project_dir": &pd }));
+    let text = get_text(&resp);
+    let parsed: Value = serde_json::from_str(&text).unwrap();
+    let feature_sid = parsed["session_id"].as_str().unwrap().to_string();
+
+    call_tool(
+        "handoff_save_context",
+        json!({
+            "project_dir": &pd,
+            "summary": "urgent fix",
+            "pause_session_id": &feature_sid
+        }),
+    );
+
+    let resp2 = call_tool("handoff_load_context", json!({ "project_dir": &pd }));
+    let text2 = get_text(&resp2);
+    let parsed2: Value = serde_json::from_str(&text2).unwrap();
+    assert!(
+        parsed2["last_session"]["summary"]
+            .as_str()
+            .unwrap()
+            .contains("urgent fix"),
+        "should load the new session"
+    );
+    assert!(
+        parsed2["paused_sessions"].as_array().unwrap().len() == 1,
+        "should show 1 paused session"
+    );
+
+    let urgent_sid = parsed2["session_id"].as_str().unwrap().to_string();
+    call_tool(
+        "handoff_save_context",
+        json!({
+            "project_dir": &pd,
+            "summary": "urgent fix done",
+            "close_session_id": &urgent_sid
+        }),
+    );
+
+    let resp3 = call_tool(
+        "handoff_load_context",
+        json!({ "project_dir": &pd, "session_id": &feature_sid }),
+    );
+    let text3 = get_text(&resp3);
+    let parsed3: Value = serde_json::from_str(&text3).unwrap();
+    assert_eq!(
+        parsed3["session_id"].as_str().unwrap(),
+        feature_sid,
+        "should resume the paused feature session"
+    );
+    assert!(
+        parsed3
+            .get("paused_sessions")
+            .and_then(|v| v.as_array())
+            .is_none()
+            || parsed3["paused_sessions"].as_array().unwrap().is_empty(),
+        "no more paused sessions after resume"
+    );
+}
+
+// --- active session uniqueness tests ---
+
+#[test]
+fn load_context_rejects_activate_when_another_session_active() {
+    let dir = setup_project();
+    let pd = dir.path().to_string_lossy().to_string();
+
+    // Create session A and activate it
+    call_tool(
+        "handoff_save_context",
+        json!({ "project_dir": &pd, "summary": "session A" }),
+    );
+    let resp = call_tool("handoff_load_context", json!({ "project_dir": &pd }));
+    let text = get_text(&resp);
+    let parsed: Value = serde_json::from_str(&text).unwrap();
+    let sid_a = parsed["session_id"].as_str().unwrap().to_string();
+
+    // Create session B (without closing A — use close_session_id to close only A's open)
+    // Actually: save_context default closes active + open, so A gets closed.
+    // We need to simulate the scenario: write a second open session manually
+    // while A is still active. We'll use pause to keep A alive.
+    call_tool(
+        "handoff_save_context",
+        json!({
+            "project_dir": &pd,
+            "summary": "session B",
+            "pause_session_id": &sid_a
+        }),
+    );
+
+    // Now: A is paused, B is open. Load B (activates it).
+    let resp = call_tool("handoff_load_context", json!({ "project_dir": &pd }));
+    assert!(!is_error(&resp));
+    let text = get_text(&resp);
+    let parsed: Value = serde_json::from_str(&text).unwrap();
+    let sid_b = parsed["session_id"].as_str().unwrap().to_string();
+
+    // Try to resume A while B is active — should fail
+    let resp = call_tool(
+        "handoff_load_context",
+        json!({ "project_dir": &pd, "session_id": &sid_a }),
+    );
+    assert!(
+        is_error(&resp),
+        "should reject activating A while B is active: {}",
+        get_text(&resp)
+    );
+    let text = get_text(&resp);
+    assert!(
+        text.contains("already active"),
+        "error should mention active session: {text}"
+    );
+    assert!(
+        text.contains(&sid_b),
+        "error should mention the blocking session ID: {text}"
+    );
+}
+
+#[test]
+fn load_context_allows_reloading_already_active_session() {
+    let dir = setup_project();
+    let pd = dir.path().to_string_lossy().to_string();
+
+    call_tool(
+        "handoff_save_context",
+        json!({ "project_dir": &pd, "summary": "session A" }),
+    );
+
+    let resp = call_tool("handoff_load_context", json!({ "project_dir": &pd }));
+    let text = get_text(&resp);
+    let parsed: Value = serde_json::from_str(&text).unwrap();
+    let sid = parsed["session_id"].as_str().unwrap().to_string();
+
+    // Loading the same session again should succeed (idempotent)
+    let resp2 = call_tool(
+        "handoff_load_context",
+        json!({ "project_dir": &pd, "session_id": &sid }),
+    );
+    assert!(
+        !is_error(&resp2),
+        "reloading the same active session should succeed: {}",
+        get_text(&resp2)
+    );
+    let text2 = get_text(&resp2);
+    let parsed2: Value = serde_json::from_str(&text2).unwrap();
+    assert_eq!(parsed2["session_id"].as_str().unwrap(), sid);
+}
+
+#[test]
+fn load_context_returns_active_session_without_open() {
+    let dir = setup_project();
+    let pd = dir.path().to_string_lossy().to_string();
+
+    call_tool(
+        "handoff_save_context",
+        json!({ "project_dir": &pd, "summary": "my session" }),
+    );
+
+    // First load activates the open session
+    let resp = call_tool("handoff_load_context", json!({ "project_dir": &pd }));
+    let text = get_text(&resp);
+    let parsed: Value = serde_json::from_str(&text).unwrap();
+    let sid = parsed["session_id"].as_str().unwrap().to_string();
+
+    // Second load (no session_id) should return the active session
+    let resp2 = call_tool("handoff_load_context", json!({ "project_dir": &pd }));
+    assert!(!is_error(&resp2), "error: {}", get_text(&resp2));
+    let text2 = get_text(&resp2);
+    let parsed2: Value = serde_json::from_str(&text2).unwrap();
+    assert_eq!(
+        parsed2["session_id"].as_str().unwrap(),
+        sid,
+        "should return the same active session"
+    );
+}