handoff-mcp-server 0.16.0 → 0.17.0

package/Cargo.lock

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

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.16.0"
+version = "0.17.0"
 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.0",
   "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();

package/src/mcp/handlers/update_session.rs

@@ -10,21 +10,28 @@ pub fn handle(arguments: &Value) -> Result<String> {
     let handoff = ensure_handoff_exists(&project_dir)?;
     let sessions_dir = handoff.join("sessions");
 
+    let target_session_id = arguments.get("session_id").and_then(|v| v.as_str());
+
     let active = read_active_sessions(&sessions_dir)?;
     if active.is_empty() {
         anyhow::bail!(
             "No active session. Call save_context with session_status='active' to create one first."
         );
     }
-    if active.len() > 1 {
-        let ids: Vec<String> = active.iter().filter_map(|s| s.id.clone()).collect();
-        anyhow::bail!(
-            "Multiple active sessions ({}). Use save_context to resolve.",
-            ids.join(", ")
-        );
-    }
 
-    let session = &active[0];
+    let session = 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))
+            })
+            .ok_or_else(|| anyhow::anyhow!("session_id '{tid}' not found among active sessions"))?
+    } else if active.len() == 1 {
+        &active[0]
+    } else {
+        active.last().unwrap()
+    };
     let sid = session.id.as_deref().unwrap_or("");
 
     let checklist_index = arguments

package/src/mcp/handlers/update_task.rs

@@ -247,6 +247,15 @@ fn handle_update(
     }
     if let Some(notes) = task_val.get("notes").and_then(|v| v.as_str()) {
         data.notes = Some(notes.to_string());
+    } else if let Some(append) = task_val.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 let Some(priority) = task_val.get("priority").and_then(|v| v.as_str()) {
         validate_priority(Some(priority))?;

package/src/mcp/tools.rs

@@ -168,6 +168,23 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     "environment": {
                         "type": "object",
                         "description": "Free-form environment state"
+                    },
+                    "session_id": {
+                        "type": "string",
+                        "description": "Target active session ID. When multiple active sessions exist, specifies which to update/close. If omitted, uses the latest active session. Lower priority than close_session_id / pause_session_id."
+                    },
+                    "timeline": {
+                        "type": "string",
+                        "description": "Session timeline/group label (e.g. 'feature-x', 'hotfix-y')."
+                    },
+                    "label": {
+                        "type": "string",
+                        "description": "Short human-readable session label for switching UI (e.g. 'WT2作業', 'API設計')."
+                    },
+                    "related_task_ids": {
+                        "type": "array",
+                        "description": "Task IDs this session is primarily working on.",
+                        "items": { "type": "string" }
                     }
                 },
                 "required": ["summary"]
@@ -272,6 +289,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                                 "enum": ["todo", "in_progress", "review", "done", "blocked", "skipped"]
                             },
                             "notes": { "type": "string" },
+                            "notes_append": { "type": "string", "description": "Append text to existing notes with a timestamp heading. If both notes and notes_append are provided, notes (replace) takes precedence." },
                             "priority": {
                                 "type": "string",
                                 "enum": ["low", "medium", "high"]
@@ -695,6 +713,10 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                         "type": "string",
                         "description": "Project directory path. Defaults to current working directory."
                     },
+                    "session_id": {
+                        "type": "string",
+                        "description": "Target active session ID. When multiple active sessions exist, specifies which to update. If omitted and multiple exist, uses the latest."
+                    },
                     "checklist_index": {
                         "type": "integer",
                         "description": "0-based index of a checklist item to toggle."
@@ -798,9 +820,17 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                         "enum": ["open", "active", "paused", "closed"],
                         "description": "Filter sessions by status."
                     },
+                    "timeline": {
+                        "type": "string",
+                        "description": "Filter sessions by timeline label."
+                    },
                     "limit": {
                         "type": "integer",
                         "description": "Max sessions to return (default 20)."
+                    },
+                    "include_children": {
+                        "type": "boolean",
+                        "description": "If true, include a 'children' array on each session showing its forked child sessions."
                     }
                 }
             }),
@@ -838,6 +868,8 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                                 "status": { "type": "string", "enum": ["todo", "in_progress", "review", "done", "blocked", "skipped"] },
                                 "priority": { "type": "string", "enum": ["low", "medium", "high"] },
                                 "assignee": { "type": "string" },
+                                "notes": { "type": "string", "description": "Replace task notes." },
+                                "notes_append": { "type": "string", "description": "Append text to existing notes with a timestamp heading. If both notes and notes_append are provided, notes (replace) takes precedence." },
                                 "schedule": {
                                     "type": "object",
                                     "properties": {
@@ -1082,6 +1114,74 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 }
             }),
         },
+        // ---- Session fork/merge tools ----
+        ToolDefinition {
+            name: "handoff_fork_session".to_string(),
+            description: "Fork a new session from an existing one. Inherits decisions, context_pointers, references, and handoff_notes by default. The forked session becomes active with parent_session_id set.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "source_session_id": {
+                        "type": "string",
+                        "description": "Session ID to fork from (active, paused, or closed)."
+                    },
+                    "summary": {
+                        "type": "string",
+                        "description": "Summary for the new forked session."
+                    },
+                    "label": {
+                        "type": "string",
+                        "description": "Short human-readable label for the forked session."
+                    },
+                    "timeline": {
+                        "type": "string",
+                        "description": "Timeline label. Defaults to the source session's timeline."
+                    },
+                    "inherit": {
+                        "type": "array",
+                        "description": "Fields to inherit from the source. Default: [\"decisions\", \"context_pointers\", \"references\", \"handoff_notes\", \"environment\"]. Available: decisions, context_pointers, references, handoff_notes, environment, blockers, checklist.",
+                        "items": { "type": "string" }
+                    },
+                    "related_task_ids": {
+                        "type": "array",
+                        "description": "Task IDs the forked session will work on.",
+                        "items": { "type": "string" }
+                    }
+                },
+                "required": ["source_session_id", "summary"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_merge_sessions".to_string(),
+            description: "Merge multiple sessions into one. Combines decisions, notes, references, and context_pointers. Detects duplicate decisions as conflicts. Source sessions (except the target) are closed by default.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "source_session_ids": {
+                        "type": "array",
+                        "description": "Session IDs to merge (must include at least 2).",
+                        "items": { "type": "string" }
+                    },
+                    "target_session_id": {
+                        "type": "string",
+                        "description": "Which source session becomes the merge target (must be one of source_session_ids)."
+                    },
+                    "close_sources": {
+                        "type": "boolean",
+                        "description": "Close non-target source sessions after merge. Default: true."
+                    }
+                },
+                "required": ["source_session_ids", "target_session_id"]
+            }),
+        },
         // ---- Timer coordination tools ----
         ToolDefinition {
             name: "handoff_timer_start".to_string(),

package/src/storage/config.rs

@@ -90,6 +90,9 @@ pub struct SettingsConfig {
     /// Idle timeout in minutes for MCP fallback timer. Default 10.
     #[serde(default = "default_timer_idle_timeout_minutes")]
     pub timer_idle_timeout_minutes: u64,
+    /// Allow multiple active sessions simultaneously. Default false (single-active).
+    #[serde(default)]
+    pub multi_session: bool,
     #[serde(default)]
     pub custom_fields: HashMap<String, toml::Value>,
 }
@@ -295,6 +298,7 @@ impl Default for SettingsConfig {
             timer_provider: default_timer_provider(),
             timer_authority_ttl_secs: default_timer_authority_ttl_secs(),
             timer_idle_timeout_minutes: default_timer_idle_timeout_minutes(),
+            multi_session: false,
             custom_fields: HashMap::new(),
         }
     }
@@ -311,6 +315,10 @@ impl Default for DashboardConfig {
 
 impl Config {
     pub fn new(name: &str, description: &str) -> Self {
+        let settings = SettingsConfig {
+            multi_session: true,
+            ..SettingsConfig::default()
+        };
         Self {
             project: ProjectConfig {
                 name: name.to_string(),
@@ -320,7 +328,7 @@ impl Config {
                     Some(description.to_string())
                 },
             },
-            settings: SettingsConfig::default(),
+            settings,
             dashboard: DashboardConfig::default(),
             started_at: None,
             schedule_mode: None,

package/src/storage/sessions.rs

@@ -32,6 +32,14 @@ pub struct SessionData {
     pub context_pointers: Vec<Value>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub environment: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timeline: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub label: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub parent_session_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub related_task_ids: Vec<String>,
 }
 
 pub fn generate_session_id() -> String {
@@ -169,13 +177,12 @@ pub fn read_active_sessions(sessions_dir: &Path) -> Result<Vec<SessionData>> {
     read_sessions_by_status(sessions_dir, "active")
 }
 
-/// Append `decision` (a decision object: {decision, reason?, confidence?}) to the
-/// `decisions` list of every active session file. Returns the number of sessions
-/// updated. Used by tools like auto_schedule to record applied changes so the
-/// audit trail lives with the session, not just the tool response.
+/// Append `decision` to active session(s). When `target_session_id` is Some,
+/// only the matching session is updated; otherwise all active sessions are updated.
 pub fn append_decision_to_active_sessions(
     sessions_dir: &Path,
     decision: serde_json::Value,
+    target_session_id: Option<&str>,
 ) -> Result<usize> {
     let suffix = ".active.json";
     if !sessions_dir.exists() {
@@ -194,6 +201,14 @@ pub fn append_decision_to_active_sessions(
             .with_context(|| format!("Failed to read session: {}", path.display()))?;
         let mut data: SessionData = serde_json::from_str(&content)
             .with_context(|| format!("Failed to parse session: {}", path.display()))?;
+
+        if let Some(tid) = target_session_id {
+            let file_id = data.id.as_deref().unwrap_or("");
+            if !ids_match(file_id, tid) {
+                continue;
+            }
+        }
+
         data.decisions.push(decision.clone());
         let updated = serde_json::to_string_pretty(&data).context("Failed to serialize session")?;
         crate::storage::atomic_write(&path, updated.as_bytes())
@@ -369,6 +384,15 @@ fn apply_session_updates(data: &mut SessionData, updates: &SessionData) {
     if updates.environment.is_some() {
         data.environment = updates.environment.clone();
     }
+    if updates.timeline.is_some() {
+        data.timeline = updates.timeline.clone();
+    }
+    if updates.label.is_some() {
+        data.label = updates.label.clone();
+    }
+    if !updates.related_task_ids.is_empty() {
+        data.related_task_ids = updates.related_task_ids.clone();
+    }
 }
 
 fn find_and_update_active_session(
@@ -467,6 +491,277 @@ pub fn update_active_session(
     find_and_update_active_session(sessions_dir, session_id, updates, None)
 }
 
+pub fn read_session_by_id(sessions_dir: &Path, session_id: &str) -> Result<Option<SessionData>> {
+    if !sessions_dir.exists() {
+        return Ok(None);
+    }
+
+    let mut matches: Vec<(SessionData, String)> = Vec::new();
+
+    for entry in std::fs::read_dir(sessions_dir)? {
+        let entry = entry?;
+        let name = entry.file_name().to_string_lossy().to_string();
+        if !name.ends_with(".json") {
+            continue;
+        }
+        let content = std::fs::read_to_string(entry.path())
+            .with_context(|| format!("Failed to read session: {}", entry.path().display()))?;
+        let data: SessionData = serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse session: {}", entry.path().display()))?;
+
+        let file_id = data.id.as_deref().unwrap_or("");
+        let resolved_id = if file_id.is_empty() {
+            synthesize_id_from_filename(&name)
+        } else {
+            file_id.to_string()
+        };
+
+        if ids_match(&resolved_id, session_id) {
+            matches.push((data, resolved_id));
+        }
+    }
+
+    if matches.len() > 1 {
+        let candidates: Vec<&str> = matches.iter().map(|(_, id)| id.as_str()).collect();
+        anyhow::bail!(
+            "Ambiguous session_id '{}': matched {} sessions ({}). Provide a more specific ID.",
+            session_id,
+            matches.len(),
+            candidates.join(", ")
+        );
+    }
+
+    Ok(matches.into_iter().next().map(|(data, _)| data))
+}
+
+pub fn fork_session(
+    sessions_dir: &Path,
+    source: &SessionData,
+    summary: &str,
+    label: Option<&str>,
+    timeline: Option<&str>,
+    related_task_ids: Vec<String>,
+    inherit: &[&str],
+) -> Result<SessionData> {
+    let source_id = source
+        .id
+        .as_deref()
+        .ok_or_else(|| anyhow::anyhow!("Source session has no ID"))?;
+
+    let mut forked = SessionData {
+        version: source.version,
+        id: Some(generate_session_id()),
+        ended_at: None,
+        summary: summary.to_string(),
+        branch: None,
+        commit: None,
+        dirty_files: Vec::new(),
+        decisions: Vec::new(),
+        blockers: Vec::new(),
+        checklist: Vec::new(),
+        handoff_notes: Vec::new(),
+        references: Vec::new(),
+        context_pointers: Vec::new(),
+        environment: None,
+        timeline: timeline
+            .map(String::from)
+            .or_else(|| source.timeline.clone()),
+        label: label.map(String::from),
+        parent_session_id: Some(source_id.to_string()),
+        related_task_ids,
+    };
+
+    for field in inherit {
+        match *field {
+            "decisions" => forked.decisions = source.decisions.clone(),
+            "context_pointers" => forked.context_pointers = source.context_pointers.clone(),
+            "references" => forked.references = source.references.clone(),
+            "handoff_notes" => forked.handoff_notes = source.handoff_notes.clone(),
+            "environment" => forked.environment = source.environment.clone(),
+            "blockers" => forked.blockers = source.blockers.clone(),
+            "checklist" => forked.checklist = source.checklist.clone(),
+            _ => {}
+        }
+    }
+
+    write_session_with_status(sessions_dir, &forked, "active")?;
+    Ok(forked)
+}
+
+pub fn merge_sessions(
+    sessions_dir: &Path,
+    source_ids: &[&str],
+    target_id: &str,
+    close_sources: bool,
+) -> Result<MergeResult> {
+    let mut sources: Vec<SessionData> = Vec::new();
+    for sid in source_ids {
+        let session = read_session_by_id(sessions_dir, sid)?
+            .ok_or_else(|| anyhow::anyhow!("Source session not found: {sid}"))?;
+        sources.push(session);
+    }
+
+    let mut target = read_session_by_id(sessions_dir, target_id)?
+        .ok_or_else(|| anyhow::anyhow!("Target session not found: {target_id}"))?;
+
+    let target_actual_id = target.id.clone().unwrap_or_default();
+
+    let mut merged_decisions = 0usize;
+    let mut merged_notes = 0usize;
+    let mut merged_references = 0usize;
+    let mut merged_context_pointers = 0usize;
+    let mut conflicts = Vec::new();
+    let mut closed_sessions = Vec::new();
+
+    for source in &sources {
+        let source_actual_id = source.id.as_deref().unwrap_or("");
+        if source_actual_id == target_actual_id {
+            continue;
+        }
+
+        for d in &source.decisions {
+            let decision_text = d.get("decision").and_then(|v| v.as_str()).unwrap_or("");
+            let already_exists = target.decisions.iter().any(|td| {
+                td.get("decision").and_then(|v| v.as_str()).unwrap_or("") == decision_text
+            });
+            if already_exists {
+                conflicts.push(MergeConflict {
+                    conflict_type: "decision_conflict".to_string(),
+                    description: format!("Duplicate decision: {decision_text}"),
+                    session_a: target_actual_id.clone(),
+                    session_b: source_actual_id.to_string(),
+                });
+            } else {
+                target.decisions.push(d.clone());
+                merged_decisions += 1;
+            }
+        }
+
+        for n in &source.handoff_notes {
+            target.handoff_notes.push(n.clone());
+            merged_notes += 1;
+        }
+
+        for r in &source.references {
+            let label = r.get("label").and_then(|v| v.as_str()).unwrap_or("");
+            let already_exists = target
+                .references
+                .iter()
+                .any(|tr| tr.get("label").and_then(|v| v.as_str()).unwrap_or("") == label);
+            if !already_exists {
+                target.references.push(r.clone());
+                merged_references += 1;
+            }
+        }
+
+        for cp in &source.context_pointers {
+            let path = cp.get("path").and_then(|v| v.as_str()).unwrap_or("");
+            let already_exists = target
+                .context_pointers
+                .iter()
+                .any(|tcp| tcp.get("path").and_then(|v| v.as_str()).unwrap_or("") == path);
+            if !already_exists {
+                target.context_pointers.push(cp.clone());
+                merged_context_pointers += 1;
+            }
+        }
+
+        for task_id in &source.related_task_ids {
+            if !target.related_task_ids.contains(task_id) {
+                target.related_task_ids.push(task_id.clone());
+            }
+        }
+
+        if close_sources {
+            if let Some(path) = close_session_by_id(sessions_dir, source_actual_id)? {
+                let _ = path;
+                closed_sessions.push(source_actual_id.to_string());
+            }
+        }
+    }
+
+    update_session_in_place(sessions_dir, &target_actual_id, &target)?;
+
+    Ok(MergeResult {
+        merged_session_id: target_actual_id,
+        merged_decisions,
+        merged_notes,
+        merged_references,
+        merged_context_pointers,
+        conflicts,
+        closed_sessions,
+    })
+}
+
+fn update_session_in_place(
+    sessions_dir: &Path,
+    session_id: &str,
+    updated: &SessionData,
+) -> Result<()> {
+    if !sessions_dir.exists() {
+        anyhow::bail!("Sessions directory not found");
+    }
+
+    let mut matches: Vec<(PathBuf, String)> = Vec::new();
+
+    for entry in std::fs::read_dir(sessions_dir)? {
+        let entry = entry?;
+        let name = entry.file_name().to_string_lossy().to_string();
+        if !name.ends_with(".json") {
+            continue;
+        }
+        let content = std::fs::read_to_string(entry.path())?;
+        let data: SessionData = serde_json::from_str(&content)?;
+        let file_id = data.id.as_deref().unwrap_or("");
+        let resolved_id = if file_id.is_empty() {
+            synthesize_id_from_filename(&name)
+        } else {
+            file_id.to_string()
+        };
+        if ids_match(&resolved_id, session_id) {
+            matches.push((entry.path(), resolved_id));
+        }
+    }
+
+    if matches.len() > 1 {
+        let candidates: Vec<&str> = matches.iter().map(|(_, id)| id.as_str()).collect();
+        anyhow::bail!(
+            "Ambiguous session_id '{}': matched {} sessions ({}). Provide a more specific ID.",
+            session_id,
+            matches.len(),
+            candidates.join(", ")
+        );
+    }
+
+    if let Some((path, _)) = matches.into_iter().next() {
+        let serialized =
+            serde_json::to_string_pretty(updated).context("Failed to serialize session")?;
+        crate::storage::atomic_write(path, serialized.as_bytes())?;
+        return Ok(());
+    }
+
+    anyhow::bail!("Session not found for in-place update: {session_id}")
+}
+
+#[derive(Debug)]
+pub struct MergeConflict {
+    pub conflict_type: String,
+    pub description: String,
+    pub session_a: String,
+    pub session_b: String,
+}
+
+#[derive(Debug)]
+pub struct MergeResult {
+    pub merged_session_id: String,
+    pub merged_decisions: usize,
+    pub merged_notes: usize,
+    pub merged_references: usize,
+    pub merged_context_pointers: usize,
+    pub conflicts: Vec<MergeConflict>,
+    pub closed_sessions: Vec<String>,
+}
+
 pub fn enforce_history_limit(sessions_dir: &Path, limit: u32) -> Result<u32> {
     if !sessions_dir.exists() {
         return Ok(0);