handoff-mcp-server 0.16.0 → 0.17.1

package/Cargo.lock

@@ -136,7 +136,7 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.16.0"
+version = "0.17.1"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

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

package/README.md

@@ -177,6 +177,8 @@ manual configuration alternative.
 | `handoff_update_session` | Incrementally update active session (toggle checklist, add decisions/notes/pointers) |
 | `handoff_list_sessions` | List all sessions (open/active/paused/closed) with summary info |
 | `handoff_get_session` | Get full detail of a specific session by ID |
+| `handoff_fork_session` | Fork a new session from an existing one with context inheritance |
+| `handoff_merge_sessions` | Merge multiple sessions into one with conflict detection |
 
 ### Task Management
 
@@ -184,7 +186,7 @@ manual configuration alternative.
 |------|---------|
 | `handoff_list_tasks` | List tasks with filters (status, assignee, milestone, priority, label) |
 | `handoff_get_task` | Get full task details (notes, done_criteria, schedule, etc.) |
-| `handoff_update_task` | Create, update, or move tasks in a hierarchical tree |
+| `handoff_update_task` | Create, update, or move tasks; supports `notes_append` for safe incremental notes |
 | `handoff_check_criterion` | Toggle a single done_criteria item by index |
 | `handoff_log_time` | Log hours worked — adds to `actual_hours`, deducts from `remaining_hours` |
 | `handoff_bulk_update_tasks` | Update multiple tasks in one call (status, schedule, assignee, priority) |
@@ -319,6 +321,7 @@ history_limit = 20            # Max closed sessions to keep
 done_task_limit = 10          # Max completed tasks to show
 auto_git_summary = true       # Capture git state automatically
 require_estimate_hours = true # Require estimate_hours on leaf tasks (default true)
+multi_session = true          # Allow multiple active sessions (default true for new projects)
 ai_estimate_multiplier = 0.2  # Multiplier turning human estimates into AI-effort hours
 timer_provider = "auto"       # "auto" | "vscode" | "mcp" | "off"
 timer_authority_ttl_secs = 30 # Heartbeat freshness TTL for authority.json

package/package.json

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

package/skills/handoff/SKILL.md

@@ -62,6 +62,16 @@ description: "Session handoff — load context at start, save at end, track task
   aggregation time by `handoff_get_metrics`/`handoff_get_capacity`. To turn the
   requirement off, set `settings.require_estimate_hours = false`.
 
+### Appending to Task Notes
+- Use `notes_append` (not `notes`) in `handoff_update_task` or
+  `handoff_bulk_update_tasks` to add text to existing task notes without
+  replacing them. The server adds a `--- YYYY-MM-DDTHH:MM:SS` timestamp
+  heading automatically.
+- This is safe for multi-agent/multi-step workflows — no read-modify-write
+  needed, no risk of losing prior notes.
+- If both `notes` (replace) and `notes_append` are provided in the same call,
+  `notes` takes precedence and `notes_append` is ignored.
+
 ### Progressive done_criteria Checking
 - **Check off `done_criteria` immediately as each item is verified** — do not
   wait until the entire task is finished. Use `handoff_check_criterion` to
@@ -162,10 +172,26 @@ Before assigning dates to tasks, check available capacity:
 - `handoff_update_labels` — set the project-level label vocabulary (`labels` array).
 - `handoff_start_project` — set `started_at` and, with `shift_dates: true`, move every task's dates so the earliest start lands on the project start date.
 
+### Multi-session
+
+When `multi_session = true` (default for new projects), multiple active sessions
+can coexist. Use `session_id` on load/save/update to target a specific one.
+
+- `handoff_fork_session` — branch from an existing session. Inherits decisions,
+  context_pointers, references, handoff_notes by default. Sets
+  `parent_session_id`. Source can be active, paused, or closed.
+- `handoff_merge_sessions` — combine multiple sessions (append mode). Detects
+  duplicate decisions as conflicts. Non-target sources closed by default.
+- **Switch**: `handoff_save_context(pause_session_id: "s-current")` then
+  `handoff_load_context(session_id: "s-target")`.
+- **Session fields**: `timeline` (grouping label), `label` (short name),
+  `parent_session_id` (fork origin), `related_task_ids` (task association).
+
 ### Session Browsing
 
-- `handoff_list_sessions` — list all sessions with status filter (open/active/paused/closed) and limit.
-- `handoff_get_session` — get full detail of any session by ID (decisions, checklist, handoff_notes, context_pointers, references).
+- `handoff_list_sessions` — list sessions; filter by status, `timeline`;
+  `include_children: true` adds child session arrays for branching visualization.
+- `handoff_get_session` — get full detail of any session by ID (decisions, checklist, handoff_notes, context_pointers, references, timeline, parent_session_id).
 - Use these to reference decisions or context from past sessions without needing to re-read the full session file.
 
 ### Bulk Operations

package/src/mcp/handlers/auto_schedule.rs

@@ -157,8 +157,11 @@ pub fn handle(arguments: &Value) -> Result<String> {
             "confidence": "confirmed",
         });
         let sessions_dir = handoff.join("sessions");
-        decision_recorded_in =
-            crate::storage::sessions::append_decision_to_active_sessions(&sessions_dir, decision)?;
+        decision_recorded_in = crate::storage::sessions::append_decision_to_active_sessions(
+            &sessions_dir,
+            decision,
+            None,
+        )?;
     }
 
     let result = json!({

package/src/mcp/handlers/bulk_update.rs

@@ -55,6 +55,19 @@ fn apply_single_update(tasks_dir: &std::path::Path, task_id: &str, update: &Valu
         data.priority = Some(priority.to_string());
     }
 
+    if let Some(notes) = update.get("notes").and_then(|v| v.as_str()) {
+        data.notes = Some(notes.to_string());
+    } else if let Some(append) = update.get("notes_append").and_then(|v| v.as_str()) {
+        let timestamp = Utc::now().format("%Y-%m-%dT%H:%M:%S");
+        let block = format!("--- {timestamp}\n{append}");
+        match &mut data.notes {
+            Some(existing) if !existing.is_empty() => {
+                existing.push_str(&format!("\n\n{block}"));
+            }
+            _ => data.notes = Some(block),
+        }
+    }
+
     if update.get("assignee").is_some() {
         data.assignee = update
             .get("assignee")

package/src/mcp/handlers/fork_session.rs

@@ -0,0 +1,91 @@
+use anyhow::Result;
+use serde_json::{json, Value};
+
+use super::resolve_project_dir;
+use crate::storage::ensure_handoff_exists;
+use crate::storage::sessions::{fork_session, read_session_by_id};
+
+pub fn handle(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+    let handoff = ensure_handoff_exists(&project_dir)?;
+    let sessions_dir = handoff.join("sessions");
+
+    let source_session_id = arguments
+        .get("source_session_id")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("'source_session_id' parameter is required"))?;
+
+    let summary = arguments
+        .get("summary")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("'summary' parameter is required"))?;
+
+    let label = arguments.get("label").and_then(|v| v.as_str());
+    let timeline = arguments.get("timeline").and_then(|v| v.as_str());
+
+    let related_task_ids: Vec<String> = arguments
+        .get("related_task_ids")
+        .and_then(|v| v.as_array())
+        .map(|arr| {
+            arr.iter()
+                .filter_map(|v| v.as_str().map(String::from))
+                .collect()
+        })
+        .unwrap_or_default();
+
+    let default_inherit = vec![
+        "decisions",
+        "context_pointers",
+        "references",
+        "handoff_notes",
+        "environment",
+    ];
+    let inherit: Vec<&str> = arguments
+        .get("inherit")
+        .and_then(|v| v.as_array())
+        .map(|arr| arr.iter().filter_map(|v| v.as_str()).collect())
+        .unwrap_or(default_inherit);
+
+    let source = read_session_by_id(&sessions_dir, source_session_id)?.ok_or_else(|| {
+        anyhow::anyhow!(
+            "Source session not found: {source_session_id}. \
+                 Use handoff_list_sessions to see available session IDs."
+        )
+    })?;
+
+    let forked = fork_session(
+        &sessions_dir,
+        &source,
+        summary,
+        label,
+        timeline,
+        related_task_ids,
+        &inherit,
+    )?;
+
+    let forked_id = forked.id.as_deref().unwrap_or("unknown");
+
+    let result = json!({
+        "session_id": forked_id,
+        "parent_session_id": source_session_id,
+        "status": "active",
+        "inherited": inherit,
+    });
+
+    let mut output = format!(
+        "Forked session: {}\nSession ID: {}\nParent: {}\nStatus: active\nInherited: {}",
+        summary,
+        forked_id,
+        source_session_id,
+        inherit.join(", "),
+    );
+    if let Some(tl) = forked.timeline.as_deref() {
+        output.push_str(&format!("\nTimeline: {tl}"));
+    }
+    if let Some(lbl) = forked.label.as_deref() {
+        output.push_str(&format!("\nLabel: {lbl}"));
+    }
+    output.push_str(&format!("\n\n{}", serde_json::to_string_pretty(&result)?));
+
+    Ok(output)
+}

package/src/mcp/handlers/import_context.rs

@@ -109,6 +109,10 @@ pub fn handle(arguments: &Value) -> Result<String> {
             references: extract_array(session, "references"),
             context_pointers: extract_array(session, "context_pointers"),
             environment: Some(environment),
+            timeline: None,
+            label: None,
+            parent_session_id: None,
+            related_task_ids: Vec::new(),
         };
 
         write_open_session(&sessions_dir, &data)?;
@@ -154,6 +158,10 @@ pub fn handle(arguments: &Value) -> Result<String> {
                         "format": source_format
                     }
                 })),
+                timeline: None,
+                label: None,
+                parent_session_id: None,
+                related_task_ids: Vec::new(),
             };
 
             write_open_session(&sessions_dir, &data)?;

package/src/mcp/handlers/list_sessions.rs

@@ -10,10 +10,15 @@ pub fn handle(arguments: &Value) -> Result<String> {
     let sessions_dir = handoff.join("sessions");
 
     let status_filter = arguments.get("status_filter").and_then(|v| v.as_str());
+    let timeline_filter = arguments.get("timeline").and_then(|v| v.as_str());
     let limit = arguments
         .get("limit")
         .and_then(|v| v.as_u64())
         .unwrap_or(20) as usize;
+    let include_children = arguments
+        .get("include_children")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false);
 
     if !sessions_dir.exists() {
         return serde_json::to_string_pretty(&json!([])).map_err(Into::into);
@@ -52,7 +57,16 @@ pub fn handle(arguments: &Value) -> Result<String> {
             .map(String::from)
             .unwrap_or_else(|| synthesize_id_from_filename(&name));
 
+        let timeline = data.get("timeline").and_then(|v| v.as_str());
+        if let Some(tl_filter) = timeline_filter {
+            if timeline.is_none_or(|tl| tl != tl_filter) {
+                continue;
+            }
+        }
+
         let summary = data.get("summary").and_then(|v| v.as_str()).unwrap_or("");
+        let label = data.get("label").and_then(|v| v.as_str());
+        let parent_session_id = data.get("parent_session_id").and_then(|v| v.as_str());
         let started_at = data.get("started_at").and_then(|v| v.as_str());
         let ended_at = data.get("ended_at").and_then(|v| v.as_str());
         let branch = data.get("branch").and_then(|v| v.as_str());
@@ -78,7 +92,7 @@ pub fn handle(arguments: &Value) -> Result<String> {
             })
             .unwrap_or(0);
 
-        sessions.push(json!({
+        let mut entry = json!({
             "id": id,
             "status": status,
             "summary": summary,
@@ -88,7 +102,17 @@ pub fn handle(arguments: &Value) -> Result<String> {
             "commit": commit,
             "decisions_count": decisions_count,
             "checklist_progress": format!("{}/{}", checklist_checked, checklist_count),
-        }));
+        });
+        if let Some(tl) = timeline {
+            entry["timeline"] = json!(tl);
+        }
+        if let Some(lbl) = label {
+            entry["label"] = json!(lbl);
+        }
+        if let Some(pid) = parent_session_id {
+            entry["parent_session_id"] = json!(pid);
+        }
+        sessions.push(entry);
     }
 
     sessions.sort_by(|a, b| {
@@ -97,8 +121,42 @@ pub fn handle(arguments: &Value) -> Result<String> {
         b_time.cmp(a_time)
     });
 
+    let all_sessions_for_children = if include_children {
+        sessions.clone()
+    } else {
+        Vec::new()
+    };
+
     sessions.truncate(limit);
 
+    if include_children {
+        for session in &mut sessions {
+            let sid = session.get("id").and_then(|v| v.as_str()).unwrap_or("");
+            if sid.is_empty() {
+                continue;
+            }
+            let children: Vec<Value> = all_sessions_for_children
+                .iter()
+                .filter(|s| {
+                    s.get("parent_session_id")
+                        .and_then(|v| v.as_str())
+                        .is_some_and(|pid| pid == sid)
+                })
+                .map(|s| {
+                    json!({
+                        "id": s.get("id").and_then(|v| v.as_str()).unwrap_or(""),
+                        "summary": s.get("summary").and_then(|v| v.as_str()).unwrap_or(""),
+                        "status": s.get("status").and_then(|v| v.as_str()).unwrap_or(""),
+                        "label": s.get("label").and_then(|v| v.as_str()),
+                    })
+                })
+                .collect();
+            if !children.is_empty() {
+                session["children"] = json!(children);
+            }
+        }
+    }
+
     serde_json::to_string_pretty(&sessions).map_err(Into::into)
 }
 

package/src/mcp/handlers/load_context.rs

@@ -44,6 +44,8 @@ pub fn handle(arguments: &Value) -> Result<String> {
     let sessions = read_open_sessions(&sessions_dir)?;
     let paused_sessions = read_paused_sessions(&sessions_dir)?;
 
+    let multi_session = config.settings.multi_session;
+
     let selected_session = if let Some(sid) = target_session_id {
         let already_active = active_sessions
             .iter()
@@ -52,7 +54,7 @@ pub fn handle(arguments: &Value) -> Result<String> {
             active_sessions
                 .into_iter()
                 .find(|s| s.id.as_deref().is_some_and(|id| id == sid))
-        } else if !active_sessions.is_empty() {
+        } else if !multi_session && !active_sessions.is_empty() {
             let active_ids: Vec<String> = active_sessions
                 .iter()
                 .filter_map(|s| s.id.clone())
@@ -60,7 +62,7 @@ pub fn handle(arguments: &Value) -> Result<String> {
             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.",
+                 close/pause the active session first, or enable multi_session in config.",
                 active_ids.join(", ")
             );
         } else if activate_session_by_id(&sessions_dir, sid)?.is_some() {
@@ -211,40 +213,23 @@ pub fn handle(arguments: &Value) -> Result<String> {
 
     let current_open = read_open_sessions(&sessions_dir)?;
     if !current_open.is_empty() {
-        let summaries: Vec<Value> = current_open
-            .iter()
-            .map(|s| {
-                serde_json::json!({
-                    "id": s.id,
-                    "summary": s.summary,
-                    "ended_at": s.ended_at,
-                    "branch": s.branch,
-                })
-            })
-            .collect();
+        let summaries: Vec<Value> = current_open.iter().map(session_summary_json).collect();
         result["open_sessions"] = serde_json::json!(summaries);
     }
 
     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();
+        let summaries: Vec<Value> = current_paused.iter().map(session_summary_json).collect();
         result["paused_sessions"] = serde_json::json!(summaries);
     }
 
-    let has_active_session = read_active_sessions(&sessions_dir)
-        .map(|s| !s.is_empty())
-        .unwrap_or(false);
-    if !has_active_session {
+    let current_active = read_active_sessions(&sessions_dir)?;
+    if current_active.len() > 1 {
+        let summaries: Vec<Value> = current_active.iter().map(session_summary_json).collect();
+        result["active_sessions"] = serde_json::json!(summaries);
+    }
+
+    if current_active.is_empty() {
         let mut guidance = serde_json::json!({
             "action": "create_session",
             "message": "No active session. Before starting work, call handoff_save_context with session_status='active' to establish a session. Include inherited context (decisions, context_pointers, references) from the previous session so your work survives interruptions."
@@ -267,11 +252,34 @@ pub fn handle(arguments: &Value) -> Result<String> {
             guidance["suggested_fields"] = suggested;
         }
         result["session_guidance"] = guidance;
+    } else if current_active.len() > 1 && target_session_id.is_none() {
+        let summaries: Vec<Value> = current_active.iter().map(session_summary_json).collect();
+        result["session_guidance"] = serde_json::json!({
+            "action": "select_session",
+            "message": "Multiple active sessions. Use session_id to specify which to work with, or create a new session.",
+            "active_sessions": summaries
+        });
     }
 
     serde_json::to_string_pretty(&result).context("Failed to serialize context")
 }
 
+fn session_summary_json(s: &crate::storage::sessions::SessionData) -> Value {
+    let mut obj = serde_json::json!({
+        "id": s.id,
+        "summary": s.summary,
+        "ended_at": s.ended_at,
+        "branch": s.branch,
+    });
+    if let Some(ref label) = s.label {
+        obj["label"] = serde_json::json!(label);
+    }
+    if let Some(ref timeline) = s.timeline {
+        obj["timeline"] = serde_json::json!(timeline);
+    }
+    obj
+}
+
 fn collect_active_task_ids(task_tree: &[TaskIndex]) -> Option<Vec<String>> {
     let mut ids = Vec::new();
     collect_active_ids_recursive(task_tree, &mut ids);

package/src/mcp/handlers/merge_sessions.rs

@@ -0,0 +1,103 @@
+use anyhow::Result;
+use serde_json::{json, Value};
+
+use super::resolve_project_dir;
+use crate::storage::ensure_handoff_exists;
+use crate::storage::sessions::merge_sessions;
+
+pub fn handle(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+    let handoff = ensure_handoff_exists(&project_dir)?;
+    let sessions_dir = handoff.join("sessions");
+
+    let source_session_ids: Vec<&str> = arguments
+        .get("source_session_ids")
+        .and_then(|v| v.as_array())
+        .ok_or_else(|| anyhow::anyhow!("'source_session_ids' parameter is required"))?
+        .iter()
+        .filter_map(|v| v.as_str())
+        .collect();
+
+    if source_session_ids.len() < 2 {
+        anyhow::bail!("'source_session_ids' must contain at least 2 session IDs");
+    }
+
+    let target_session_id = arguments
+        .get("target_session_id")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("'target_session_id' parameter is required"))?;
+
+    if !source_session_ids.contains(&target_session_id) {
+        anyhow::bail!(
+            "target_session_id '{}' must be one of the source_session_ids",
+            target_session_id
+        );
+    }
+
+    let close_sources = arguments
+        .get("close_sources")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(true);
+
+    let result = merge_sessions(
+        &sessions_dir,
+        &source_session_ids,
+        target_session_id,
+        close_sources,
+    )?;
+
+    let conflicts_json: Vec<Value> = result
+        .conflicts
+        .iter()
+        .map(|c| {
+            json!({
+                "type": c.conflict_type,
+                "description": c.description,
+                "session_a": c.session_a,
+                "session_b": c.session_b,
+            })
+        })
+        .collect();
+
+    let output_json = json!({
+        "merged_session_id": result.merged_session_id,
+        "merged_decisions": result.merged_decisions,
+        "merged_notes": result.merged_notes,
+        "merged_references": result.merged_references,
+        "merged_context_pointers": result.merged_context_pointers,
+        "conflicts": conflicts_json,
+        "closed_sessions": result.closed_sessions,
+    });
+
+    let mut output = format!(
+        "Merged {} sessions into {}\n\
+         Merged: {} decisions, {} notes, {} references, {} context_pointers",
+        source_session_ids.len(),
+        result.merged_session_id,
+        result.merged_decisions,
+        result.merged_notes,
+        result.merged_references,
+        result.merged_context_pointers,
+    );
+
+    if !result.conflicts.is_empty() {
+        output.push_str(&format!("\nConflicts: {}", result.conflicts.len()));
+        for c in &result.conflicts {
+            output.push_str(&format!("\n  - {}: {}", c.conflict_type, c.description));
+        }
+    }
+
+    if !result.closed_sessions.is_empty() {
+        output.push_str(&format!(
+            "\nClosed source sessions: {}",
+            result.closed_sessions.join(", ")
+        ));
+    }
+
+    output.push_str(&format!(
+        "\n\n{}",
+        serde_json::to_string_pretty(&output_json)?
+    ));
+
+    Ok(output)
+}

package/src/mcp/handlers/mod.rs

@@ -7,6 +7,7 @@ pub mod check_criterion;
 pub mod config;
 pub mod config_crud;
 pub mod dashboard;
+pub mod fork_session;
 pub mod get_session;
 pub mod get_task;
 pub mod import_context;
@@ -16,6 +17,7 @@ pub mod list_tasks;
 pub mod load_context;
 pub mod log_time;
 pub mod memory;
+pub mod merge_sessions;
 pub mod metrics;
 pub mod milestones;
 pub mod refer;
@@ -80,6 +82,8 @@ pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {
         "handoff_memory_query" => memory::handle_query(arguments),
         "handoff_memory_delete" => memory::handle_delete(arguments),
         "handoff_memory_cleanup" => memory::handle_cleanup(arguments),
+        "handoff_fork_session" => fork_session::handle(arguments),
+        "handoff_merge_sessions" => merge_sessions::handle(arguments),
         "handoff_timer_start" => timer::handle_start(arguments),
         "handoff_timer_stop" => timer::handle_stop(arguments),
         "handoff_timer_get_time" => timer::handle_get_time(arguments),

package/src/mcp/handlers/save_context.rs

@@ -79,6 +79,8 @@ pub fn handle(arguments: &Value) -> Result<String> {
     let git_state = capture_git_state(&project_dir)?;
     let now = Utc::now().to_rfc3339();
 
+    let target_session_id = arguments.get("session_id").and_then(|v| v.as_str());
+
     let handoff_updates = SessionData {
         version: 2,
         id: None,
@@ -94,6 +96,16 @@ pub fn handle(arguments: &Value) -> Result<String> {
         references: extract_array(arguments, "references"),
         context_pointers: extract_array(arguments, "context_pointers"),
         environment: arguments.get("environment").cloned(),
+        timeline: arguments
+            .get("timeline")
+            .and_then(|v| v.as_str())
+            .map(String::from),
+        label: arguments
+            .get("label")
+            .and_then(|v| v.as_str())
+            .map(String::from),
+        parent_session_id: None,
+        related_task_ids: extract_string_array(arguments, "related_task_ids"),
     };
 
     let (total_closed, path, session_id) = if let Some(id) = close_id {
@@ -103,16 +115,19 @@ pub fn handle(arguments: &Value) -> Result<String> {
         (0, None, None)
     } 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 context.",
-                active_ids.join(", ")
-            );
-        }
-        if let Some(active_session) = active.first() {
+        let target = if let Some(tid) = target_session_id {
+            active.iter().find(|s| {
+                s.id.as_deref()
+                    .is_some_and(|id| id == tid || id.starts_with(tid) || tid.starts_with(id))
+            })
+        } else if active.len() == 1 {
+            active.first()
+        } else if active.len() > 1 {
+            active.iter().last()
+        } else {
+            None
+        };
+        if let Some(active_session) = target {
             let sid = active_session.id.clone().unwrap_or_default();
             if keep_active {
                 let updated_path = update_active_session(&sessions_dir, &sid, &handoff_updates)?;
@@ -126,6 +141,11 @@ pub fn handle(arguments: &Value) -> Result<String> {
                     Some(sid),
                 )
             }
+        } else if target_session_id.is_some() {
+            anyhow::bail!(
+                "session_id '{}' not found among active sessions",
+                target_session_id.unwrap_or("")
+            );
         } else {
             let new_id = generate_session_id();
             let mut data = handoff_updates.clone();