handoff-mcp-server 0.1.0 → 0.2.0

package/Cargo.lock

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

package/Cargo.toml

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

package/README.md

@@ -55,9 +55,12 @@ Add to your Claude Code MCP configuration:
 
 ```json
 {
-  "handoff": {
-    "command": "handoff-mcp",
-    "args": []
+  "mcpServers": {
+    "handoff": {
+      "type": "stdio",
+      "command": "handoff-mcp",
+      "args": []
+    }
   }
 }
 ```
@@ -66,9 +69,12 @@ Add to your Claude Code MCP configuration:
 
 ```json
 {
-  "handoff": {
-    "command": "handoff-mcp",
-    "args": []
+  "mcpServers": {
+    "handoff": {
+      "type": "stdio",
+      "command": "handoff-mcp",
+      "args": []
+    }
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-mcp-server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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/import_context.rs

@@ -0,0 +1,310 @@
+use anyhow::{Context, Result};
+use chrono::Utc;
+use serde_json::Value;
+
+use super::resolve_project_dir;
+use crate::storage::config::read_config;
+use crate::storage::ensure_handoff_exists;
+use crate::storage::git::capture_git_state;
+use crate::storage::sessions::{
+    close_active_sessions, enforce_history_limit, write_active_session, SessionData,
+};
+use crate::storage::tasks::*;
+
+pub fn handle(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+    let handoff = ensure_handoff_exists(&project_dir)?;
+    let tasks_dir = handoff.join("tasks");
+    let sessions_dir = handoff.join("sessions");
+    let config_path = handoff.join("config.toml");
+
+    let source = arguments
+        .get("source")
+        .ok_or_else(|| anyhow::anyhow!("'source' parameter is required"))?;
+    let source_description = source
+        .get("description")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("'source.description' is required"))?;
+    let source_format = source
+        .get("format")
+        .and_then(|v| v.as_str())
+        .unwrap_or("other");
+
+    let mut tasks_created: u32 = 0;
+    let mut top_level_count: u32 = 0;
+    let mut nested_count: u32 = 0;
+
+    if let Some(tasks) = arguments.get("tasks").and_then(|v| v.as_array()) {
+        for task_val in tasks {
+            let title = task_val
+                .get("title")
+                .and_then(|v| v.as_str())
+                .ok_or_else(|| anyhow::anyhow!("Each task requires a 'title'"))?;
+
+            let task_id = next_top_level_id(&tasks_dir)?;
+            let count = create_task_recursive(&tasks_dir, &task_id, None, title, task_val)?;
+            tasks_created += count;
+            top_level_count += 1;
+            nested_count += count - 1;
+        }
+    }
+
+    let mut session_saved = false;
+    if let Some(session) = arguments.get("session") {
+        let summary = session
+            .get("summary")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| {
+                anyhow::anyhow!("'session.summary' is required when session is provided")
+            })?;
+
+        let closed = close_active_sessions(&sessions_dir)?;
+        let git_state = capture_git_state(&project_dir)?;
+        let now = Utc::now().to_rfc3339();
+
+        let mut handoff_notes = extract_array(session, "handoff_notes");
+
+        if let Some(raw_notes) = arguments.get("raw_notes").and_then(|v| v.as_str()) {
+            if !raw_notes.is_empty() {
+                handoff_notes.push(serde_json::json!({
+                    "note": raw_notes,
+                    "category": "context"
+                }));
+            }
+        }
+
+        let mut environment = session
+            .get("environment")
+            .cloned()
+            .unwrap_or(serde_json::json!({}));
+        if let Some(env_obj) = environment.as_object_mut() {
+            env_obj.insert(
+                "import_source".to_string(),
+                serde_json::json!({
+                    "description": source_description,
+                    "format": source_format
+                }),
+            );
+        }
+
+        let data = SessionData {
+            version: 2,
+            ended_at: Some(now),
+            summary: summary.to_string(),
+            branch: Some(git_state.branch),
+            commit: Some(git_state.commit),
+            dirty_files: git_state.dirty_files,
+            decisions: extract_array(session, "decisions"),
+            blockers: extract_string_array(session, "blockers"),
+            checklist: extract_array(session, "checklist"),
+            handoff_notes,
+            references: extract_array(session, "references"),
+            context_pointers: extract_array(session, "context_pointers"),
+            environment: Some(environment),
+        };
+
+        write_active_session(&sessions_dir, &data)?;
+
+        let history_limit = if config_path.exists() {
+            read_config(&config_path)
+                .map(|c| c.settings.history_limit)
+                .unwrap_or(20)
+        } else {
+            20
+        };
+        enforce_history_limit(&sessions_dir, history_limit)?;
+
+        let _ = closed;
+        session_saved = true;
+    } else if let Some(raw_notes) = arguments.get("raw_notes").and_then(|v| v.as_str()) {
+        if !raw_notes.is_empty() {
+            let closed = close_active_sessions(&sessions_dir)?;
+            let git_state = capture_git_state(&project_dir)?;
+            let now = Utc::now().to_rfc3339();
+
+            let data = SessionData {
+                version: 2,
+                ended_at: Some(now),
+                summary: format!("[import] {source_description}"),
+                branch: Some(git_state.branch),
+                commit: Some(git_state.commit),
+                dirty_files: git_state.dirty_files,
+                decisions: Vec::new(),
+                blockers: Vec::new(),
+                checklist: Vec::new(),
+                handoff_notes: vec![serde_json::json!({
+                    "note": raw_notes,
+                    "category": "context"
+                })],
+                references: Vec::new(),
+                context_pointers: Vec::new(),
+                environment: Some(serde_json::json!({
+                    "import_source": {
+                        "description": source_description,
+                        "format": source_format
+                    }
+                })),
+            };
+
+            write_active_session(&sessions_dir, &data)?;
+
+            let history_limit = if config_path.exists() {
+                read_config(&config_path)
+                    .map(|c| c.settings.history_limit)
+                    .unwrap_or(20)
+            } else {
+                20
+            };
+            enforce_history_limit(&sessions_dir, history_limit)?;
+
+            let _ = closed;
+            session_saved = true;
+        }
+    }
+
+    let mut msg = format!("Import complete:\n  Source: {source_description}");
+
+    if tasks_created > 0 {
+        msg.push_str(&format!(
+            "\n  Tasks created: {tasks_created} ({top_level_count} top-level, {nested_count} nested)"
+        ));
+    } else {
+        msg.push_str("\n  Tasks created: 0");
+    }
+
+    if session_saved {
+        msg.push_str("\n  Session saved: yes");
+    }
+
+    if arguments
+        .get("raw_notes")
+        .and_then(|v| v.as_str())
+        .is_some_and(|s| !s.is_empty())
+    {
+        msg.push_str("\n  Raw notes: saved as handoff_note (context)");
+    }
+
+    Ok(msg)
+}
+
+fn create_task_recursive(
+    tasks_dir: &std::path::Path,
+    task_id: &str,
+    parent_dir: Option<&std::path::Path>,
+    title: &str,
+    task_val: &Value,
+) -> Result<u32> {
+    let slug = title_to_slug(title);
+    let dir_name = format!("{task_id}-{slug}");
+    let base_dir = parent_dir.unwrap_or(tasks_dir);
+    let task_dir = base_dir.join(&dir_name);
+
+    std::fs::create_dir_all(&task_dir)
+        .with_context(|| format!("Failed to create task dir: {}", task_dir.display()))?;
+
+    let now = Utc::now().to_rfc3339();
+    let status = task_val
+        .get("status")
+        .and_then(|v| v.as_str())
+        .unwrap_or("todo");
+
+    if !is_valid_status(status) {
+        anyhow::bail!("Invalid status: {status}");
+    }
+
+    let completed_at = if is_terminal_status(status) {
+        Some(now.clone())
+    } else {
+        None
+    };
+
+    let data = TaskData {
+        id: task_id.to_string(),
+        title: title.to_string(),
+        notes: task_val
+            .get("notes")
+            .and_then(|v| v.as_str())
+            .map(String::from),
+        priority: task_val
+            .get("priority")
+            .and_then(|v| v.as_str())
+            .map(String::from),
+        created_at: Some(now.clone()),
+        updated_at: Some(now),
+        completed_at,
+        labels: extract_string_array_from(task_val, "labels"),
+        links: extract_string_array_from(task_val, "links"),
+        done_criteria: extract_done_criteria(task_val),
+    };
+
+    write_task(&task_dir, status, &data)?;
+
+    let mut count: u32 = 1;
+
+    if let Some(children) = task_val.get("children").and_then(|v| v.as_array()) {
+        for (i, child_val) in children.iter().enumerate() {
+            let child_title = child_val
+                .get("title")
+                .and_then(|v| v.as_str())
+                .ok_or_else(|| anyhow::anyhow!("Each child task requires a 'title'"))?;
+
+            let child_id = format!("{task_id}.{}", i + 1);
+            count += create_task_recursive(
+                &task_dir,
+                &child_id,
+                Some(&task_dir),
+                child_title,
+                child_val,
+            )?;
+        }
+    }
+
+    Ok(count)
+}
+
+fn extract_array(val: &Value, key: &str) -> Vec<Value> {
+    val.get(key)
+        .and_then(|v| v.as_array())
+        .cloned()
+        .unwrap_or_default()
+}
+
+fn extract_string_array(val: &Value, key: &str) -> Vec<String> {
+    val.get(key)
+        .and_then(|v| v.as_array())
+        .map(|arr| {
+            arr.iter()
+                .filter_map(|v| v.as_str().map(String::from))
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn extract_string_array_from(val: &Value, key: &str) -> Vec<String> {
+    val.get(key)
+        .and_then(|v| v.as_array())
+        .map(|arr| {
+            arr.iter()
+                .filter_map(|v| v.as_str().map(String::from))
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn extract_done_criteria(val: &Value) -> Vec<DoneCriterion> {
+    val.get("done_criteria")
+        .and_then(|v| v.as_array())
+        .map(|arr| {
+            arr.iter()
+                .filter_map(|v| {
+                    let item = v.get("item")?.as_str()?;
+                    let checked = v.get("checked").and_then(|c| c.as_bool()).unwrap_or(false);
+                    Some(DoneCriterion {
+                        item: item.to_string(),
+                        checked,
+                    })
+                })
+                .collect()
+        })
+        .unwrap_or_default()
+}

package/src/mcp/handlers/mod.rs

@@ -1,5 +1,6 @@
 pub mod config;
 pub mod dashboard;
+pub mod import_context;
 pub mod init;
 pub mod list_tasks;
 pub mod load_context;
@@ -31,6 +32,7 @@ pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {
         "handoff_dashboard" => dashboard::handle(arguments),
         "handoff_get_config" => config::handle_get(arguments),
         "handoff_update_config" => config::handle_update(arguments),
+        "handoff_import_context" => import_context::handle(arguments),
         _ => Err(anyhow::anyhow!("Tool not implemented: {name}")),
     };
 

package/src/mcp/tools.rs

@@ -263,6 +263,170 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 }
             }),
         },
+        ToolDefinition {
+            name: "handoff_import_context".to_string(),
+            description: "Import existing handoff documents into .handoff/ management. AI reads the source material, structures it, and submits everything in one call. Supports nested task hierarchies via children field.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "source": {
+                        "type": "object",
+                        "description": "Metadata about the original document being imported",
+                        "properties": {
+                            "description": {
+                                "type": "string",
+                                "description": "What is being imported (e.g. 'tmp/260601-sprint-handoff.md からの移行')"
+                            },
+                            "format": {
+                                "type": "string",
+                                "enum": ["markdown", "json", "text", "other"],
+                                "description": "Format of the source material. Defaults to 'other'."
+                            }
+                        },
+                        "required": ["description"]
+                    },
+                    "tasks": {
+                        "type": "array",
+                        "description": "Tasks to import. Supports nested hierarchies via children field.",
+                        "items": {
+                            "$ref": "#/$defs/importTask"
+                        }
+                    },
+                    "session": {
+                        "type": "object",
+                        "description": "Session context to save. Same fields as handoff_save_context.",
+                        "properties": {
+                            "summary": { "type": "string", "description": "One-line summary (required)" },
+                            "decisions": {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "properties": {
+                                        "decision": { "type": "string" },
+                                        "reason": { "type": "string" },
+                                        "confidence": {
+                                            "type": "string",
+                                            "enum": ["confirmed", "estimated", "unverified"]
+                                        }
+                                    },
+                                    "required": ["decision"]
+                                }
+                            },
+                            "blockers": {
+                                "type": "array",
+                                "items": { "type": "string" }
+                            },
+                            "checklist": {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "properties": {
+                                        "item": { "type": "string" },
+                                        "checked": { "type": "boolean" },
+                                        "owner": { "type": "string", "enum": ["user", "ai"] }
+                                    },
+                                    "required": ["item"]
+                                }
+                            },
+                            "handoff_notes": {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "properties": {
+                                        "note": { "type": "string" },
+                                        "category": { "type": "string", "enum": ["caution", "context", "suggestion"] }
+                                    },
+                                    "required": ["note"]
+                                }
+                            },
+                            "references": {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "properties": {
+                                        "label": { "type": "string" },
+                                        "uri": { "type": "string" },
+                                        "type": { "type": "string", "enum": ["file", "issue", "mr", "wiki", "doc", "url"] },
+                                        "notes": { "type": "string" }
+                                    },
+                                    "required": ["label", "uri"]
+                                }
+                            },
+                            "context_pointers": {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "properties": {
+                                        "path": { "type": "string" },
+                                        "reason": { "type": "string" },
+                                        "lines": { "type": "string" }
+                                    },
+                                    "required": ["path"]
+                                }
+                            },
+                            "environment": {
+                                "type": "object",
+                                "description": "Free-form environment state"
+                            }
+                        },
+                        "required": ["summary"]
+                    },
+                    "raw_notes": {
+                        "type": "string",
+                        "description": "Free-form text that couldn't be structured. Saved as a handoff_note with category 'context'."
+                    }
+                },
+                "required": ["source"],
+                "$defs": {
+                    "importTask": {
+                        "type": "object",
+                        "properties": {
+                            "title": { "type": "string" },
+                            "status": {
+                                "type": "string",
+                                "enum": ["todo", "in_progress", "review", "done", "blocked", "skipped"]
+                            },
+                            "notes": { "type": "string" },
+                            "priority": {
+                                "type": "string",
+                                "enum": ["low", "medium", "high"]
+                            },
+                            "labels": {
+                                "type": "array",
+                                "items": { "type": "string" }
+                            },
+                            "links": {
+                                "type": "array",
+                                "items": { "type": "string" }
+                            },
+                            "done_criteria": {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "properties": {
+                                        "item": { "type": "string" },
+                                        "checked": { "type": "boolean" }
+                                    },
+                                    "required": ["item"]
+                                }
+                            },
+                            "children": {
+                                "type": "array",
+                                "description": "Nested child tasks. Recursively supports the same structure.",
+                                "items": {
+                                    "$ref": "#/$defs/importTask"
+                                }
+                            }
+                        },
+                        "required": ["title"]
+                    }
+                }
+            }),
+        },
     ]
 }
 

package/src/storage/sessions.rs

@@ -39,10 +39,17 @@ pub fn generate_session_filename(summary: &str, timestamp: &str) -> String {
 
 fn summary_to_slug(summary: &str) -> String {
     let slug: String = summary
-        .to_lowercase()
         .chars()
         .take(40)
-        .map(|c| if c.is_ascii_alphanumeric() { c } else { '-' })
+        .map(|c| {
+            if c.is_ascii_alphanumeric() {
+                c.to_ascii_lowercase()
+            } else if !c.is_ascii() {
+                c
+            } else {
+                '-'
+            }
+        })
         .collect();
     let slug = slug.trim_matches('-').to_string();
     let mut result = String::new();

package/src/storage/tasks.rs

@@ -66,9 +66,16 @@ pub fn is_terminal_status(status: &str) -> bool {
 
 pub fn title_to_slug(title: &str) -> String {
     let slug: String = title
-        .to_lowercase()
         .chars()
-        .map(|c| if c.is_ascii_alphanumeric() { c } else { '-' })
+        .map(|c| {
+            if c.is_ascii_alphanumeric() {
+                c.to_ascii_lowercase()
+            } else if !c.is_ascii() {
+                c
+            } else {
+                '-'
+            }
+        })
         .collect();
     let slug = slug.trim_matches('-').to_string();
     let mut result = String::new();

package/tests/tool_import_context.rs

@@ -0,0 +1,377 @@
+use serde_json::{json, Value};
+use tempfile::TempDir;
+
+fn send(input: &str) -> Option<Value> {
+    let result = handoff_mcp::mcp::protocol::process_line(input)?;
+    Some(serde_json::from_str(&result).expect("response should be valid JSON"))
+}
+
+fn setup_project() -> TempDir {
+    let dir = tempfile::tempdir().expect("failed to create temp dir");
+
+    std::process::Command::new("git")
+        .args(["init"])
+        .current_dir(dir.path())
+        .output()
+        .unwrap();
+    std::process::Command::new("git")
+        .args(["commit", "--allow-empty", "-m", "init"])
+        .current_dir(dir.path())
+        .output()
+        .unwrap();
+
+    let req = json!({
+        "jsonrpc": "2.0", "id": 0,
+        "method": "tools/call",
+        "params": {
+            "name": "handoff_init",
+            "arguments": {
+                "project_dir": dir.path().to_string_lossy(),
+                "project_name": "test"
+            }
+        }
+    });
+    send(&req.to_string()).unwrap();
+    dir
+}
+
+fn call_tool(name: &str, arguments: Value) -> Value {
+    let req = json!({
+        "jsonrpc": "2.0", "id": 1,
+        "method": "tools/call",
+        "params": { "name": name, "arguments": arguments }
+    });
+    send(&req.to_string()).unwrap()
+}
+
+fn get_text(resp: &Value) -> String {
+    resp["result"]["content"][0]["text"]
+        .as_str()
+        .unwrap_or("")
+        .to_string()
+}
+
+#[test]
+fn import_source_only() {
+    let dir = setup_project();
+    let resp = call_tool(
+        "handoff_import_context",
+        json!({
+            "project_dir": dir.path().to_string_lossy(),
+            "source": {
+                "description": "test import",
+                "format": "markdown"
+            }
+        }),
+    );
+    let text = get_text(&resp);
+    assert!(text.contains("Import complete"));
+    assert!(text.contains("Tasks created: 0"));
+}
+
+#[test]
+fn import_flat_tasks() {
+    let dir = setup_project();
+    let resp = call_tool(
+        "handoff_import_context",
+        json!({
+            "project_dir": dir.path().to_string_lossy(),
+            "source": { "description": "flat task import" },
+            "tasks": [
+                { "title": "Task A", "status": "todo" },
+                { "title": "Task B", "status": "in_progress", "priority": "high" }
+            ]
+        }),
+    );
+    let text = get_text(&resp);
+    assert!(text.contains("Tasks created: 2"));
+    assert!(text.contains("2 top-level"));
+    assert!(text.contains("0 nested"));
+
+    let list_resp = call_tool(
+        "handoff_list_tasks",
+        json!({ "project_dir": dir.path().to_string_lossy() }),
+    );
+    let list_text = get_text(&list_resp);
+    assert!(list_text.contains("Task A"));
+    assert!(list_text.contains("Task B"));
+}
+
+#[test]
+fn import_nested_tasks() {
+    let dir = setup_project();
+    let resp = call_tool(
+        "handoff_import_context",
+        json!({
+            "project_dir": dir.path().to_string_lossy(),
+            "source": { "description": "nested import" },
+            "tasks": [
+                {
+                    "title": "Parent",
+                    "status": "in_progress",
+                    "children": [
+                        { "title": "Child 1", "status": "done" },
+                        {
+                            "title": "Child 2",
+                            "status": "todo",
+                            "children": [
+                                { "title": "Grandchild", "status": "todo" }
+                            ]
+                        }
+                    ]
+                }
+            ]
+        }),
+    );
+    let text = get_text(&resp);
+    assert!(text.contains("Tasks created: 4"));
+    assert!(text.contains("1 top-level"));
+    assert!(text.contains("3 nested"));
+
+    let list_resp = call_tool(
+        "handoff_list_tasks",
+        json!({ "project_dir": dir.path().to_string_lossy() }),
+    );
+    let list_text = get_text(&list_resp);
+    assert!(list_text.contains("Parent"));
+    assert!(list_text.contains("Child 1"));
+    assert!(list_text.contains("Child 2"));
+    assert!(list_text.contains("Grandchild"));
+}
+
+#[test]
+fn import_with_session() {
+    let dir = setup_project();
+    let resp = call_tool(
+        "handoff_import_context",
+        json!({
+            "project_dir": dir.path().to_string_lossy(),
+            "source": { "description": "session import" },
+            "session": {
+                "summary": "[import] test session",
+                "decisions": [
+                    { "decision": "Use OAuth2", "reason": "mobile support", "confidence": "confirmed" }
+                ],
+                "blockers": ["waiting on API key"],
+                "handoff_notes": [
+                    { "note": "check auth flow", "category": "caution" }
+                ]
+            }
+        }),
+    );
+    let text = get_text(&resp);
+    assert!(text.contains("Session saved: yes"));
+
+    let load_resp = call_tool(
+        "handoff_load_context",
+        json!({ "project_dir": dir.path().to_string_lossy() }),
+    );
+    let load_text = get_text(&load_resp);
+    assert!(load_text.contains("[import] test session"));
+    assert!(load_text.contains("Use OAuth2"));
+    assert!(load_text.contains("waiting on API key"));
+}
+
+#[test]
+fn import_with_raw_notes() {
+    let dir = setup_project();
+    let resp = call_tool(
+        "handoff_import_context",
+        json!({
+            "project_dir": dir.path().to_string_lossy(),
+            "source": { "description": "raw notes import" },
+            "session": {
+                "summary": "[import] with raw notes"
+            },
+            "raw_notes": "Deploy on Fridays is forbidden\nSSL cert expires 7/1"
+        }),
+    );
+    let text = get_text(&resp);
+    assert!(text.contains("Raw notes: saved as handoff_note"));
+
+    let load_resp = call_tool(
+        "handoff_load_context",
+        json!({ "project_dir": dir.path().to_string_lossy() }),
+    );
+    let load_text = get_text(&load_resp);
+    assert!(load_text.contains("Deploy on Fridays is forbidden"));
+}
+
+#[test]
+fn import_raw_notes_without_session_creates_auto_session() {
+    let dir = setup_project();
+    let resp = call_tool(
+        "handoff_import_context",
+        json!({
+            "project_dir": dir.path().to_string_lossy(),
+            "source": { "description": "auto session test" },
+            "raw_notes": "Some unstructured notes"
+        }),
+    );
+    let text = get_text(&resp);
+    assert!(text.contains("Session saved: yes"));
+    assert!(text.contains("Raw notes: saved as handoff_note"));
+
+    let load_resp = call_tool(
+        "handoff_load_context",
+        json!({ "project_dir": dir.path().to_string_lossy() }),
+    );
+    let load_text = get_text(&load_resp);
+    assert!(load_text.contains("[import] auto session test"));
+    assert!(load_text.contains("Some unstructured notes"));
+}
+
+#[test]
+fn import_full_scenario() {
+    let dir = setup_project();
+    let resp = call_tool(
+        "handoff_import_context",
+        json!({
+            "project_dir": dir.path().to_string_lossy(),
+            "source": {
+                "description": "tmp/260601-sprint-handoff.md",
+                "format": "markdown"
+            },
+            "tasks": [
+                {
+                    "title": "Auth renewal",
+                    "status": "in_progress",
+                    "priority": "high",
+                    "labels": ["auth"],
+                    "children": [
+                        { "title": "Session migration", "status": "done" },
+                        { "title": "PKCE implementation", "status": "in_progress" }
+                    ]
+                },
+                {
+                    "title": "CI speedup",
+                    "status": "todo",
+                    "priority": "medium",
+                    "done_criteria": [
+                        { "item": "Build time under 5min", "checked": false }
+                    ]
+                }
+            ],
+            "session": {
+                "summary": "[import] Sprint handoff migration",
+                "decisions": [
+                    { "decision": "OAuth2 + PKCE", "confidence": "confirmed" }
+                ],
+                "blockers": ["DB migration window TBD"],
+                "references": [
+                    { "label": "Original doc", "uri": "tmp/260601-sprint-handoff.md", "type": "doc" }
+                ],
+                "context_pointers": [
+                    { "path": "src/auth/oauth.rs", "reason": "PKCE core" }
+                ]
+            },
+            "raw_notes": "Deploy on Fridays is forbidden"
+        }),
+    );
+    let text = get_text(&resp);
+    assert!(text.contains("Tasks created: 4"));
+    assert!(text.contains("2 top-level"));
+    assert!(text.contains("2 nested"));
+    assert!(text.contains("Session saved: yes"));
+    assert!(text.contains("Raw notes: saved as handoff_note"));
+}
+
+#[test]
+fn import_without_source_fails() {
+    let dir = setup_project();
+    let resp = call_tool(
+        "handoff_import_context",
+        json!({
+            "project_dir": dir.path().to_string_lossy(),
+            "tasks": [{ "title": "Something" }]
+        }),
+    );
+    let text = get_text(&resp);
+    assert!(text.contains("Error"));
+    assert!(text.contains("source"));
+}
+
+#[test]
+fn import_task_without_title_fails() {
+    let dir = setup_project();
+    let resp = call_tool(
+        "handoff_import_context",
+        json!({
+            "project_dir": dir.path().to_string_lossy(),
+            "source": { "description": "bad task" },
+            "tasks": [{ "status": "todo" }]
+        }),
+    );
+    let text = get_text(&resp);
+    assert!(text.contains("Error"));
+    assert!(text.contains("title"));
+}
+
+#[test]
+fn import_preserves_existing_tasks() {
+    let dir = setup_project();
+
+    call_tool(
+        "handoff_update_task",
+        json!({
+            "project_dir": dir.path().to_string_lossy(),
+            "task": { "title": "Pre-existing task", "status": "in_progress" }
+        }),
+    );
+
+    call_tool(
+        "handoff_import_context",
+        json!({
+            "project_dir": dir.path().to_string_lossy(),
+            "source": { "description": "import after existing" },
+            "tasks": [
+                { "title": "Imported task", "status": "todo" }
+            ]
+        }),
+    );
+
+    let list_resp = call_tool(
+        "handoff_list_tasks",
+        json!({ "project_dir": dir.path().to_string_lossy() }),
+    );
+    let list_text = get_text(&list_resp);
+    assert!(list_text.contains("Pre-existing task"));
+    assert!(list_text.contains("Imported task"));
+}
+
+#[test]
+fn import_source_recorded_in_environment() {
+    let dir = setup_project();
+    call_tool(
+        "handoff_import_context",
+        json!({
+            "project_dir": dir.path().to_string_lossy(),
+            "source": {
+                "description": "my-handoff.md",
+                "format": "markdown"
+            },
+            "session": {
+                "summary": "[import] env test"
+            }
+        }),
+    );
+
+    let sessions_dir = dir.path().join(".handoff/sessions");
+    let entries: Vec<_> = std::fs::read_dir(&sessions_dir)
+        .unwrap()
+        .filter_map(|e| e.ok())
+        .filter(|e| e.file_name().to_string_lossy().ends_with(".active.json"))
+        .collect();
+    assert_eq!(entries.len(), 1);
+
+    let content = std::fs::read_to_string(entries[0].path()).unwrap();
+    let session: serde_json::Value = serde_json::from_str(&content).unwrap();
+    assert_eq!(
+        session["environment"]["import_source"]["description"],
+        "my-handoff.md"
+    );
+    assert_eq!(
+        session["environment"]["import_source"]["format"],
+        "markdown"
+    );
+}