path: root/makima/docs/PLAN-resume-history-system.md

# Resume and History System - Implementation Plan

## Overview

This document provides a detailed, actionable implementation plan for the Resume and History System. The system enables users to view historical conversation data, resume interrupted work, and rewind/restore to previous states in the Makima platform.

**Key Reference Documents:**
- Specification: Resume and History System Specification
- Requirements: Requirements Document
- User Stories: User Stories Document

---

## Phase 1: Database Schema

**Objective:** Create the foundational database structures for storing conversation snapshots, history events, and supporting task forking.

### Task 1.1: Create Database Migrations

**Files to Create:**
- `makima/migrations/20250117000000_history_tables.sql`

**Schema Changes:**

```sql
-- 1. Conversation Snapshots table
-- Stores conversation state at specific points for rewind capability
CREATE TABLE IF NOT EXISTS conversation_snapshots (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    task_id UUID NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
    checkpoint_id UUID REFERENCES task_checkpoints(id) ON DELETE SET NULL,
    snapshot_type VARCHAR(50) NOT NULL,  -- 'auto', 'manual', 'checkpoint'
    message_count INTEGER NOT NULL,
    conversation_state JSONB NOT NULL,  -- Full conversation at this point
    metadata JSONB,  -- Additional context (token count, cost, etc.)
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_conversation_snapshots_task ON conversation_snapshots(task_id);
CREATE INDEX idx_conversation_snapshots_checkpoint ON conversation_snapshots(checkpoint_id);
CREATE INDEX idx_conversation_snapshots_created ON conversation_snapshots(created_at DESC);

-- 2. History Events table
-- Unified event stream for timeline views
CREATE TABLE IF NOT EXISTS history_events (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    owner_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    contract_id UUID REFERENCES contracts(id) ON DELETE CASCADE,
    task_id UUID REFERENCES tasks(id) ON DELETE CASCADE,
    event_type VARCHAR(50) NOT NULL,  -- 'task', 'chat', 'checkpoint', 'phase', 'file'
    event_subtype VARCHAR(50),  -- Specific event: 'created', 'completed', 'message', etc.
    phase VARCHAR(50),  -- Contract phase when event occurred
    event_data JSONB NOT NULL,  -- Event-specific data
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_history_events_contract ON history_events(contract_id, created_at DESC);
CREATE INDEX idx_history_events_task ON history_events(task_id, created_at DESC);
CREATE INDEX idx_history_events_owner ON history_events(owner_id, created_at DESC);
CREATE INDEX idx_history_events_type ON history_events(event_type, created_at DESC);

-- 3. Alter task_checkpoints - add conversation snapshot reference
ALTER TABLE task_checkpoints
    ADD COLUMN conversation_snapshot_id UUID REFERENCES conversation_snapshots(id) ON DELETE SET NULL;

-- 4. Alter tasks - add forking fields
ALTER TABLE tasks
    ADD COLUMN forked_from_task_id UUID REFERENCES tasks(id) ON DELETE SET NULL,
    ADD COLUMN forked_at_checkpoint_id UUID REFERENCES task_checkpoints(id) ON DELETE SET NULL;

CREATE INDEX idx_tasks_forked_from ON tasks(forked_from_task_id) WHERE forked_from_task_id IS NOT NULL;

-- Comments for documentation
COMMENT ON TABLE conversation_snapshots IS 'Stores conversation state at specific points for rewind/resume capability';
COMMENT ON TABLE history_events IS 'Unified event stream for timeline views across contracts and tasks';
COMMENT ON COLUMN conversation_snapshots.snapshot_type IS 'Type: auto (periodic), manual (user-triggered), checkpoint (at git checkpoint)';
COMMENT ON COLUMN history_events.event_type IS 'Category: task, chat, checkpoint, phase, file';
```

**Complexity:** Medium
**Dependencies:** None
**Estimated Time:** 2-3 hours

---

## Phase 2: Repository Layer

**Objective:** Implement database access functions for conversation snapshots, history events, and enhanced checkpoint operations.

### Task 2.1: Core Models

**Files to Modify:**
- `makima/src/db/models.rs`

**New Types to Add:**

```rust
// ConversationSnapshot model
#[derive(Debug, Clone, FromRow, Serialize, ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct ConversationSnapshot {
    pub id: Uuid,
    pub task_id: Uuid,
    pub checkpoint_id: Option<Uuid>,
    pub snapshot_type: String,  // 'auto', 'manual', 'checkpoint'
    pub message_count: i32,
    #[sqlx(json)]
    pub conversation_state: serde_json::Value,
    #[sqlx(json)]
    pub metadata: Option<serde_json::Value>,
    pub created_at: DateTime<Utc>,
}

// HistoryEvent model
#[derive(Debug, Clone, FromRow, Serialize, ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct HistoryEvent {
    pub id: Uuid,
    pub owner_id: Uuid,
    pub contract_id: Option<Uuid>,
    pub task_id: Option<Uuid>,
    pub event_type: String,
    pub event_subtype: Option<String>,
    pub phase: Option<String>,
    #[sqlx(json)]
    pub event_data: serde_json::Value,
    pub created_at: DateTime<Utc>,
}

// Unified ConversationMessage for API responses
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct ConversationMessage {
    pub id: String,
    pub role: String,  // 'user', 'assistant', 'system', 'tool'
    pub content: String,
    pub timestamp: DateTime<Utc>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_calls: Option<Vec<ToolCallInfo>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_name: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_input: Option<serde_json::Value>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_result: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub is_error: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub token_count: Option<i32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cost_usd: Option<f64>,
}

#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct ToolCallInfo {
    pub id: String,
    pub name: String,
    pub input: serde_json::Value,
}

// Query filters for history
#[derive(Debug, Deserialize, ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct HistoryQueryFilters {
    pub phase: Option<String>,
    pub event_types: Option<Vec<String>>,
    pub from: Option<DateTime<Utc>>,
    pub to: Option<DateTime<Utc>>,
    pub limit: Option<i32>,
    pub cursor: Option<String>,
}

// Resume request types
#[derive(Debug, Deserialize, ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct ResumeSupervisorRequest {
    pub target_daemon_id: Option<Uuid>,
    pub resume_mode: String,  // 'continue', 'restart_phase', 'from_checkpoint'
    pub checkpoint_id: Option<Uuid>,
    pub additional_context: Option<String>,
}

#[derive(Debug, Deserialize, ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct ResumeFromCheckpointRequest {
    pub task_name: Option<String>,
    pub plan: String,
    pub include_conversation: Option<bool>,
    pub target_daemon_id: Option<Uuid>,
}

// Rewind request types
#[derive(Debug, Deserialize, ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct RewindTaskRequest {
    pub checkpoint_id: Option<Uuid>,
    pub checkpoint_sha: Option<String>,
    pub preserve_mode: String,  // 'discard', 'create_branch', 'stash'
    pub branch_name: Option<String>,
}

#[derive(Debug, Deserialize, ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct RewindConversationRequest {
    pub to_message_id: Option<String>,
    pub to_timestamp: Option<DateTime<Utc>>,
    pub by_message_count: Option<i32>,
    pub rewind_code: Option<bool>,
}

// Fork request type
#[derive(Debug, Deserialize, ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct ForkTaskRequest {
    pub fork_from_type: String,  // 'checkpoint', 'timestamp', 'message_id'
    pub fork_from_value: String,
    pub new_task_name: String,
    pub new_task_plan: String,
    pub include_conversation: Option<bool>,
    pub create_branch: Option<bool>,
    pub branch_name: Option<String>,
}
```

**Complexity:** Medium
**Dependencies:** Phase 1 complete
**Estimated Time:** 2-3 hours

### Task 2.2: Repository Functions

**Files to Modify:**
- `makima/src/db/repository.rs`

**Functions to Add:**

```rust
// ============================================================================
// Conversation Snapshots
// ============================================================================

/// Create a new conversation snapshot
pub async fn create_conversation_snapshot(
    pool: &PgPool,
    task_id: Uuid,
    checkpoint_id: Option<Uuid>,
    snapshot_type: &str,
    message_count: i32,
    conversation_state: serde_json::Value,
    metadata: Option<serde_json::Value>,
) -> Result<ConversationSnapshot, sqlx::Error>

/// Get a conversation snapshot by ID
pub async fn get_conversation_snapshot(
    pool: &PgPool,
    id: Uuid,
) -> Result<Option<ConversationSnapshot>, sqlx::Error>

/// Get conversation snapshot at a specific checkpoint
pub async fn get_conversation_at_checkpoint(
    pool: &PgPool,
    checkpoint_id: Uuid,
) -> Result<Option<ConversationSnapshot>, sqlx::Error>

/// List conversation snapshots for a task
pub async fn list_conversation_snapshots(
    pool: &PgPool,
    task_id: Uuid,
    limit: Option<i32>,
) -> Result<Vec<ConversationSnapshot>, sqlx::Error>

/// Delete conversation snapshots older than retention period
pub async fn cleanup_old_snapshots(
    pool: &PgPool,
    retention_days: i32,
) -> Result<u64, sqlx::Error>

// ============================================================================
// History Events
// ============================================================================

/// Record a new history event
pub async fn record_history_event(
    pool: &PgPool,
    owner_id: Uuid,
    contract_id: Option<Uuid>,
    task_id: Option<Uuid>,
    event_type: &str,
    event_subtype: Option<&str>,
    phase: Option<&str>,
    event_data: serde_json::Value,
) -> Result<HistoryEvent, sqlx::Error>

/// Get contract history timeline
pub async fn get_contract_history(
    pool: &PgPool,
    contract_id: Uuid,
    owner_id: Uuid,
    filters: &HistoryQueryFilters,
) -> Result<(Vec<HistoryEvent>, i64), sqlx::Error>

/// Get task history
pub async fn get_task_history(
    pool: &PgPool,
    task_id: Uuid,
    owner_id: Uuid,
    filters: &HistoryQueryFilters,
) -> Result<(Vec<HistoryEvent>, i64), sqlx::Error>

/// Get unified timeline for an owner
pub async fn get_timeline(
    pool: &PgPool,
    owner_id: Uuid,
    filters: &HistoryQueryFilters,
) -> Result<(Vec<HistoryEvent>, i64), sqlx::Error>

// ============================================================================
// Task Conversation Retrieval
// ============================================================================

/// Get task conversation messages (reconstructed from task_events)
pub async fn get_task_conversation(
    pool: &PgPool,
    task_id: Uuid,
    include_tool_calls: bool,
    include_tool_results: bool,
    limit: Option<i32>,
) -> Result<Vec<ConversationMessage>, sqlx::Error>

/// Get supervisor conversation (from supervisor_states)
pub async fn get_supervisor_conversation(
    pool: &PgPool,
    contract_id: Uuid,
) -> Result<Option<(SupervisorState, Vec<TaskSummary>)>, sqlx::Error>

// ============================================================================
// Checkpoint Operations
// ============================================================================

/// Create checkpoint with conversation snapshot
pub async fn create_checkpoint_with_snapshot(
    pool: &PgPool,
    task_id: Uuid,
    checkpoint_number: i32,
    commit_sha: &str,
    branch_name: &str,
    message: &str,
    files_changed: Option<serde_json::Value>,
    lines_added: Option<i32>,
    lines_removed: Option<i32>,
    conversation_state: serde_json::Value,
) -> Result<(TaskCheckpoint, ConversationSnapshot), sqlx::Error>

/// Get checkpoint diff information (requires daemon interaction for actual diff)
pub async fn get_checkpoint_info(
    pool: &PgPool,
    checkpoint_id: Uuid,
) -> Result<Option<(TaskCheckpoint, Option<TaskCheckpoint>)>, sqlx::Error>

// ============================================================================
// Fork Operations
// ============================================================================

/// Create forked task
pub async fn create_forked_task(
    pool: &PgPool,
    owner_id: Uuid,
    source_task_id: Uuid,
    checkpoint_id: Option<Uuid>,
    req: &CreateTaskRequest,
) -> Result<Task, sqlx::Error>
```

**Complexity:** Complex
**Dependencies:** Task 2.1 complete
**Estimated Time:** 4-5 hours

---

## Phase 3: API Endpoints

**Objective:** Implement REST API endpoints for history viewing, resume operations, and rewind/fork functionality.

### Task 3.1: History Endpoints

**Files to Create/Modify:**
- `makima/src/server/handlers/history.rs` (new file)
- `makima/src/server/handlers/mod.rs` (add module)
- `makima/src/server/mod.rs` (add routes)

**Endpoints to Implement:**

| Method | Path | Handler Function |
|--------|------|------------------|
| GET | `/api/v1/contracts/{id}/history` | `get_contract_history` |
| GET | `/api/v1/contracts/{id}/supervisor/conversation` | `get_supervisor_conversation` |
| GET | `/api/v1/mesh/tasks/{id}/conversation` | `get_task_conversation` |
| GET | `/api/v1/mesh/tasks/{id}/checkpoints/{cid}/diff` | `get_checkpoint_diff` |
| GET | `/api/v1/timeline` | `get_timeline` |

**Implementation Details:**

```rust
// makima/src/server/handlers/history.rs

/// GET /api/v1/contracts/{id}/history
/// Returns contract history timeline with filtering and pagination
#[utoipa::path(
    get,
    path = "/api/v1/contracts/{id}/history",
    params(
        ("id" = Uuid, Path, description = "Contract ID"),
        HistoryQueryFilters
    ),
    responses(
        (status = 200, body = ContractHistoryResponse),
        (status = 404, description = "Contract not found"),
    ),
    tag = "history"
)]
pub async fn get_contract_history(
    State(state): State<AppState>,
    Path(contract_id): Path<Uuid>,
    Query(filters): Query<HistoryQueryFilters>,
    auth: AuthenticatedUser,
) -> Result<Json<ContractHistoryResponse>, ApiError>

/// GET /api/v1/contracts/{id}/supervisor/conversation
/// Returns full supervisor conversation with spawned task references
#[utoipa::path(
    get,
    path = "/api/v1/contracts/{id}/supervisor/conversation",
    responses(
        (status = 200, body = SupervisorConversationResponse),
        (status = 404, description = "Supervisor not found"),
    ),
    tag = "history"
)]
pub async fn get_supervisor_conversation(
    State(state): State<AppState>,
    Path(contract_id): Path<Uuid>,
    auth: AuthenticatedUser,
) -> Result<Json<SupervisorConversationResponse>, ApiError>

/// GET /api/v1/mesh/tasks/{id}/conversation
/// Returns task conversation history
#[utoipa::path(
    get,
    path = "/api/v1/mesh/tasks/{id}/conversation",
    params(
        ("id" = Uuid, Path, description = "Task ID"),
        ("include_tool_calls" = Option<bool>, Query),
        ("include_tool_results" = Option<bool>, Query),
        ("limit" = Option<i32>, Query),
    ),
    responses(
        (status = 200, body = TaskConversationResponse),
        (status = 404, description = "Task not found"),
    ),
    tag = "history"
)]
pub async fn get_task_conversation(
    State(state): State<AppState>,
    Path(task_id): Path<Uuid>,
    Query(params): Query<TaskConversationParams>,
    auth: AuthenticatedUser,
) -> Result<Json<TaskConversationResponse>, ApiError>

/// GET /api/v1/mesh/tasks/{id}/checkpoints/{cid}/diff
/// Returns checkpoint diff (delegates to daemon for git diff)
pub async fn get_checkpoint_diff(
    State(state): State<AppState>,
    Path((task_id, checkpoint_id)): Path<(Uuid, Uuid)>,
    auth: AuthenticatedUser,
) -> Result<Json<CheckpointDiffResponse>, ApiError>

/// GET /api/v1/timeline
/// Returns unified timeline for authenticated user
pub async fn get_timeline(
    State(state): State<AppState>,
    Query(filters): Query<TimelineQueryFilters>,
    auth: AuthenticatedUser,
) -> Result<Json<TimelineResponse>, ApiError>
```

**Complexity:** Medium
**Dependencies:** Phase 2 complete
**Estimated Time:** 4-5 hours

### Task 3.2: Resume Endpoints

**Files to Modify:**
- `makima/src/server/handlers/mesh_supervisor.rs`
- `makima/src/server/handlers/mesh.rs`

**Endpoints to Implement:**

| Method | Path | Handler Function |
|--------|------|------------------|
| POST | `/api/v1/contracts/{id}/supervisor/resume` | `resume_supervisor` |
| POST | `/api/v1/mesh/tasks/{id}/checkpoints/{cid}/resume` | `resume_from_checkpoint` |
| POST | `/api/v1/mesh/tasks/{id}/continue` | `continue_task` (enhanced) |

**Implementation Details:**

```rust
// makima/src/server/handlers/mesh_supervisor.rs

/// POST /api/v1/contracts/{id}/supervisor/resume
/// Resume interrupted supervisor with specified mode
#[utoipa::path(
    post,
    path = "/api/v1/contracts/{id}/supervisor/resume",
    request_body = ResumeSupervisorRequest,
    responses(
        (status = 200, body = ResumeSupervisorResponse),
        (status = 404, description = "Contract/supervisor not found"),
        (status = 409, description = "Supervisor already running"),
    ),
    tag = "supervisor"
)]
pub async fn resume_supervisor(
    State(state): State<AppState>,
    Path(contract_id): Path<Uuid>,
    auth: AuthenticatedUser,
    Json(req): Json<ResumeSupervisorRequest>,
) -> Result<Json<ResumeSupervisorResponse>, ApiError>

// makima/src/server/handlers/mesh.rs

/// POST /api/v1/mesh/tasks/{id}/checkpoints/{cid}/resume
/// Create new task starting from specific checkpoint
#[utoipa::path(
    post,
    path = "/api/v1/mesh/tasks/{id}/checkpoints/{cid}/resume",
    request_body = ResumeFromCheckpointRequest,
    responses(
        (status = 201, body = ResumeFromCheckpointResponse),
        (status = 404, description = "Task/checkpoint not found"),
    ),
    tag = "mesh"
)]
pub async fn resume_from_checkpoint(
    State(state): State<AppState>,
    Path((task_id, checkpoint_id)): Path<(Uuid, Uuid)>,
    auth: AuthenticatedUser,
    Json(req): Json<ResumeFromCheckpointRequest>,
) -> Result<Json<ResumeFromCheckpointResponse>, ApiError>

/// POST /api/v1/mesh/tasks/{id}/continue (enhanced)
/// Enhanced with resume mode and context options
pub async fn continue_task(
    State(state): State<AppState>,
    Path(task_id): Path<Uuid>,
    auth: AuthenticatedUser,
    Json(req): Json<ContinueTaskRequest>,  // Enhanced request type
) -> Result<Json<Task>, ApiError>
```

**Complexity:** Complex
**Dependencies:** Task 3.1 complete
**Estimated Time:** 5-6 hours

### Task 3.3: Rewind and Fork Endpoints

**Files to Modify:**
- `makima/src/server/handlers/mesh.rs`
- `makima/src/server/handlers/mesh_supervisor.rs`

**Endpoints to Implement:**

| Method | Path | Handler Function |
|--------|------|------------------|
| POST | `/api/v1/mesh/tasks/{id}/rewind` | `rewind_task` |
| POST | `/api/v1/contracts/{id}/supervisor/conversation/rewind` | `rewind_conversation` |
| POST | `/api/v1/mesh/tasks/{id}/fork` | `fork_task` |
| POST | `/api/v1/mesh/tasks/{id}/checkpoints/{cid}/branch` | `branch_from_checkpoint` |

**Implementation Details:**

```rust
// makima/src/server/handlers/mesh.rs

/// POST /api/v1/mesh/tasks/{id}/rewind
/// Rewind task code to specified checkpoint
#[utoipa::path(
    post,
    path = "/api/v1/mesh/tasks/{id}/rewind",
    request_body = RewindTaskRequest,
    responses(
        (status = 200, body = RewindTaskResponse),
        (status = 404, description = "Task/checkpoint not found"),
        (status = 409, description = "Task is running"),
    ),
    tag = "mesh"
)]
pub async fn rewind_task(
    State(state): State<AppState>,
    Path(task_id): Path<Uuid>,
    auth: AuthenticatedUser,
    Json(req): Json<RewindTaskRequest>,
) -> Result<Json<RewindTaskResponse>, ApiError>

/// POST /api/v1/mesh/tasks/{id}/fork
/// Fork task from historical point
#[utoipa::path(
    post,
    path = "/api/v1/mesh/tasks/{id}/fork",
    request_body = ForkTaskRequest,
    responses(
        (status = 201, body = ForkTaskResponse),
        (status = 404, description = "Task not found"),
    ),
    tag = "mesh"
)]
pub async fn fork_task(
    State(state): State<AppState>,
    Path(task_id): Path<Uuid>,
    auth: AuthenticatedUser,
    Json(req): Json<ForkTaskRequest>,
) -> Result<Json<ForkTaskResponse>, ApiError>

/// POST /api/v1/mesh/tasks/{id}/checkpoints/{cid}/branch
/// Create git branch from checkpoint without starting task
pub async fn branch_from_checkpoint(
    State(state): State<AppState>,
    Path((task_id, checkpoint_id)): Path<(Uuid, Uuid)>,
    auth: AuthenticatedUser,
    Json(req): Json<CreateBranchFromCheckpointRequest>,
) -> Result<Json<BranchCreatedResponse>, ApiError>

// makima/src/server/handlers/mesh_supervisor.rs

/// POST /api/v1/contracts/{id}/supervisor/conversation/rewind
/// Rewind supervisor conversation to specified point
pub async fn rewind_conversation(
    State(state): State<AppState>,
    Path(contract_id): Path<Uuid>,
    auth: AuthenticatedUser,
    Json(req): Json<RewindConversationRequest>,
) -> Result<Json<RewindConversationResponse>, ApiError>
```

**Complexity:** Complex
**Dependencies:** Task 3.2 complete
**Estimated Time:** 5-6 hours

---

## Phase 4: CLI Commands

**Objective:** Implement command-line interface for history viewing, resume, and rewind operations.

### Task 4.1: History Commands

**Files to Modify:**
- `makima/src/daemon/cli/mod.rs`
- `makima/src/daemon/cli/contract.rs`
- `makima/src/daemon/cli/supervisor.rs`

**New Commands:**

```rust
// makima/src/daemon/cli/mod.rs

/// Contract subcommands - add history commands
#[derive(Subcommand, Debug)]
pub enum ContractCommand {
    // ... existing commands ...

    /// View contract history timeline
    History(contract::HistoryArgs),
}

/// Supervisor subcommands - add history and resume commands
#[derive(Subcommand, Debug)]
pub enum SupervisorCommand {
    // ... existing commands ...

    /// View task conversation history
    TaskHistory(supervisor::TaskHistoryArgs),

    /// List checkpoints with details
    CheckpointList(supervisor::CheckpointListArgs),

    /// View checkpoint diff
    CheckpointDiff(supervisor::CheckpointDiffArgs),

    /// Resume supervisor after interruption
    Resume(supervisor::ResumeArgs),
}
```

**Implementation - Contract History:**

```rust
// makima/src/daemon/cli/contract.rs

#[derive(Args, Debug)]
pub struct HistoryArgs {
    /// Filter by phase (research, specify, plan, execute, review)
    #[arg(long)]
    pub phase: Option<String>,

    /// Filter from date (ISO 8601 format)
    #[arg(long)]
    pub from: Option<String>,

    /// Filter to date (ISO 8601 format)
    #[arg(long)]
    pub to: Option<String>,

    /// Maximum entries to return
    #[arg(long, default_value = "50")]
    pub limit: i32,

    /// Output format (table, json)
    #[arg(long, default_value = "table")]
    pub format: String,
}

pub async fn handle_history(args: &HistoryArgs) -> Result<()> {
    // 1. Get contract context from environment
    // 2. Call /api/v1/contracts/{id}/history with filters
    // 3. Format and display results
}
```

**Implementation - Task History:**

```rust
// makima/src/daemon/cli/supervisor.rs

#[derive(Args, Debug)]
pub struct TaskHistoryArgs {
    /// Task ID to view history for
    pub task_id: Uuid,

    /// Include tool calls in output
    #[arg(long, default_value = "true")]
    pub tool_calls: bool,

    /// Maximum messages to return
    #[arg(long)]
    pub limit: Option<i32>,

    /// Output format (table, json, chat)
    #[arg(long, default_value = "chat")]
    pub format: String,
}

pub async fn handle_task_history(args: &TaskHistoryArgs) -> Result<()> {
    // 1. Call /api/v1/mesh/tasks/{id}/conversation
    // 2. Format as chat-style output or JSON
}

#[derive(Args, Debug)]
pub struct CheckpointListArgs {
    /// Task ID to list checkpoints for
    pub task_id: Uuid,

    /// Include diff summary
    #[arg(long)]
    pub with_diff: bool,
}

#[derive(Args, Debug)]
pub struct CheckpointDiffArgs {
    /// Task ID
    pub task_id: Uuid,

    /// Checkpoint number
    pub checkpoint_number: i32,
}
```

**Complexity:** Medium
**Dependencies:** Phase 3 complete
**Estimated Time:** 3-4 hours

### Task 4.2: Resume and Rewind Commands

**Files to Modify:**
- `makima/src/daemon/cli/supervisor.rs`
- `makima/src/daemon/cli/contract.rs`

**New Commands:**

```rust
// makima/src/daemon/cli/supervisor.rs

#[derive(Args, Debug)]
pub struct ResumeArgs {
    /// Resume mode: continue, restart_phase, from_checkpoint
    #[arg(long, default_value = "continue")]
    pub mode: String,

    /// Checkpoint ID (required for from_checkpoint mode)
    #[arg(long)]
    pub checkpoint: Option<Uuid>,

    /// Additional context to inject
    #[arg(long)]
    pub context: Option<String>,
}

pub async fn handle_resume(args: &ResumeArgs) -> Result<()> {
    // 1. Get contract context
    // 2. Call /api/v1/contracts/{id}/supervisor/resume
    // 3. Display result and new supervisor task info
}

#[derive(Args, Debug)]
pub struct TaskResumeArgs {
    /// Task ID to resume
    pub task_id: Uuid,

    /// Resume mode: with_context, clean_restart, from_checkpoint
    #[arg(long, default_value = "with_context")]
    pub mode: String,

    /// Checkpoint SHA (for from_checkpoint mode)
    #[arg(long)]
    pub checkpoint: Option<String>,
}

#[derive(Args, Debug)]
pub struct TaskResumeFromArgs {
    /// Source task ID
    pub task_id: Uuid,

    /// Checkpoint number to resume from
    #[arg(long)]
    pub checkpoint: i32,

    /// Plan for the new task
    #[arg(long)]
    pub plan: String,

    /// Name for the new task
    #[arg(long)]
    pub name: Option<String>,
}

#[derive(Args, Debug)]
pub struct TaskRewindArgs {
    /// Task ID to rewind
    pub task_id: Uuid,

    /// Checkpoint number to rewind to
    #[arg(long)]
    pub checkpoint: i32,

    /// Preserve mode: discard, create_branch, stash
    #[arg(long, default_value = "create_branch")]
    pub preserve: String,

    /// Branch name (for create_branch mode)
    #[arg(long)]
    pub branch_name: Option<String>,
}

#[derive(Args, Debug)]
pub struct TaskForkArgs {
    /// Source task ID
    pub task_id: Uuid,

    /// Checkpoint number to fork from
    #[arg(long)]
    pub checkpoint: i32,

    /// Name for the new task
    #[arg(long)]
    pub name: String,

    /// Plan for the new task
    #[arg(long)]
    pub plan: String,

    /// Include conversation history
    #[arg(long, default_value = "true")]
    pub include_conversation: bool,
}

#[derive(Args, Debug)]
pub struct ConversationRewindArgs {
    /// Number of messages to rewind
    #[arg(long)]
    pub by_messages: Option<i32>,

    /// Message ID to rewind to
    #[arg(long)]
    pub to_message: Option<String>,

    /// Also rewind code to matching checkpoint
    #[arg(long)]
    pub rewind_code: bool,
}
```

**Update CLI Commands enum:**

```rust
// makima/src/daemon/cli/mod.rs

#[derive(Subcommand, Debug)]
pub enum SupervisorCommand {
    // ... existing commands ...

    /// Resume supervisor after interruption
    Resume(supervisor::ResumeArgs),

    /// Resume task with context
    TaskResume(supervisor::TaskResumeArgs),

    /// Resume from specific checkpoint
    TaskResumeFrom(supervisor::TaskResumeFromArgs),

    /// Rewind task code to checkpoint
    TaskRewind(supervisor::TaskRewindArgs),

    /// Fork task from historical point
    TaskFork(supervisor::TaskForkArgs),

    /// Rewind supervisor conversation
    RewindConversation(supervisor::ConversationRewindArgs),
}
```

**Complexity:** Medium
**Dependencies:** Task 4.1 complete
**Estimated Time:** 4-5 hours

---

## Phase 5: Daemon Integration

**Objective:** Extend daemon protocol and handlers to support rewind operations and conversation snapshots.

### Task 5.1: Protocol Extensions

**Files to Modify:**
- `makima/src/daemon/ws/protocol.rs`
- `makima/src/server/protocol.rs` (if separate)

**New Commands to Add:**

```rust
// makima/src/daemon/ws/protocol.rs

/// Command from server to daemon
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "camelCase")]
pub enum DaemonCommand {
    // ... existing commands ...

    /// Rewind task worktree to a specific checkpoint
    RewindToCheckpoint {
        #[serde(rename = "taskId")]
        task_id: Uuid,
        #[serde(rename = "checkpointSha")]
        checkpoint_sha: String,
        /// How to preserve current state: 'discard', 'create_branch', 'stash'
        #[serde(rename = "preserveMode")]
        preserve_mode: String,
        /// Branch name for create_branch mode
        #[serde(rename = "branchName")]
        branch_name: Option<String>,
    },

    /// Create a conversation snapshot for a task
    CreateConversationSnapshot {
        #[serde(rename = "taskId")]
        task_id: Uuid,
    },

    /// Get git diff between two commits
    GetCheckpointDiff {
        #[serde(rename = "taskId")]
        task_id: Uuid,
        /// SHA of the checkpoint to diff
        #[serde(rename = "checkpointSha")]
        checkpoint_sha: String,
        /// SHA of the previous checkpoint (for comparison)
        #[serde(rename = "previousSha")]
        previous_sha: Option<String>,
    },
}

/// Message from daemon to server
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "camelCase")]
pub enum DaemonMessage {
    // ... existing messages ...

    /// Response to RewindToCheckpoint command
    RewindResult {
        #[serde(rename = "taskId")]
        task_id: Uuid,
        success: bool,
        message: String,
        /// Reference to preserved state (branch name or stash ref)
        #[serde(rename = "preservedAs")]
        preserved_as: Option<PreservedState>,
    },

    /// Response to CreateConversationSnapshot command
    ConversationSnapshotCreated {
        #[serde(rename = "taskId")]
        task_id: Uuid,
        #[serde(rename = "snapshotId")]
        snapshot_id: Uuid,
        #[serde(rename = "messageCount")]
        message_count: i32,
    },

    /// Response to GetCheckpointDiff command
    CheckpointDiffResult {
        #[serde(rename = "taskId")]
        task_id: Uuid,
        success: bool,
        diff: Option<GitDiffInfo>,
        error: Option<String>,
    },
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PreservedState {
    /// Type: 'branch' or 'stash'
    #[serde(rename = "type")]
    pub state_type: String,
    /// Branch name or stash reference
    pub reference: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct GitDiffInfo {
    pub files: Vec<FileDiffInfo>,
    pub stats: DiffStats,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct FileDiffInfo {
    pub path: String,
    /// Action: 'added', 'modified', 'deleted'
    pub action: String,
    pub additions: i32,
    pub deletions: i32,
    /// Diff hunks (optional, may be truncated for large files)
    pub hunks: Option<Vec<DiffHunk>>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DiffHunk {
    pub header: String,
    pub lines: Vec<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DiffStats {
    pub files_changed: i32,
    pub insertions: i32,
    pub deletions: i32,
}
```

**Complexity:** Medium
**Dependencies:** None (can be done in parallel with Phase 3-4)
**Estimated Time:** 2-3 hours

### Task 5.2: Daemon Handlers

**Files to Modify:**
- `makima/src/daemon/task/manager.rs`
- `makima/src/daemon/worktree/manager.rs`

**Handlers to Implement:**

```rust
// makima/src/daemon/task/manager.rs

impl TaskManager {
    /// Handle rewind to checkpoint command
    pub async fn handle_rewind_to_checkpoint(
        &mut self,
        task_id: Uuid,
        checkpoint_sha: &str,
        preserve_mode: &str,
        branch_name: Option<&str>,
    ) -> Result<RewindResult, DaemonError> {
        // 1. Validate task exists and is not running
        // 2. Get worktree path for task
        // 3. Based on preserve_mode:
        //    - 'discard': git reset --hard {sha}
        //    - 'create_branch': git branch {name} && git reset --hard {sha}
        //    - 'stash': git stash && git reset --hard {sha}
        // 4. Return result with preserved reference
    }

    /// Handle conversation snapshot creation
    pub async fn handle_create_conversation_snapshot(
        &mut self,
        task_id: Uuid,
    ) -> Result<SnapshotResult, DaemonError> {
        // 1. Get task state including conversation
        // 2. Send to server for storage
        // 3. Return snapshot ID
    }

    /// Handle checkpoint diff request
    pub async fn handle_get_checkpoint_diff(
        &mut self,
        task_id: Uuid,
        checkpoint_sha: &str,
        previous_sha: Option<&str>,
    ) -> Result<GitDiffInfo, DaemonError> {
        // 1. Get worktree path for task
        // 2. Run git diff command
        // 3. Parse and return diff info
    }
}
```

**Files to Modify:**
- `makima/src/daemon/worktree/manager.rs`

**Helper Functions:**

```rust
// makima/src/daemon/worktree/manager.rs

impl WorktreeManager {
    /// Reset worktree to specific commit
    pub async fn reset_to_commit(
        &self,
        worktree_path: &Path,
        commit_sha: &str,
    ) -> Result<(), WorktreeError>

    /// Create branch from current state
    pub async fn create_branch(
        &self,
        worktree_path: &Path,
        branch_name: &str,
    ) -> Result<(), WorktreeError>

    /// Stash current changes
    pub async fn stash_changes(
        &self,
        worktree_path: &Path,
    ) -> Result<String, WorktreeError>  // Returns stash ref

    /// Get diff between two commits
    pub async fn get_diff(
        &self,
        worktree_path: &Path,
        from_sha: &str,
        to_sha: &str,
    ) -> Result<String, WorktreeError>

    /// Parse git diff output into structured format
    pub fn parse_diff(diff_output: &str) -> Result<GitDiffInfo, ParseError>
}
```

**Complexity:** Complex
**Dependencies:** Task 5.1 complete
**Estimated Time:** 4-5 hours

### Task 5.3: Checkpoint Enhancement

**Files to Modify:**
- `makima/src/daemon/task/manager.rs`
- `makima/src/server/handlers/mesh_daemon.rs`

**Changes:**

1. **Update checkpoint creation to include conversation state:**

```rust
// When creating a checkpoint, also capture current conversation
pub async fn create_checkpoint_with_conversation(
    &mut self,
    task_id: Uuid,
    message: &str,
) -> Result<(TaskCheckpoint, ConversationSnapshot), DaemonError> {
    // 1. Create git commit (existing logic)
    // 2. Capture current conversation state
    // 3. Create checkpoint record with snapshot reference
}
```

2. **Update task spawning to handle fork/resume scenarios:**

```rust
// When spawning task with forked_from_task_id or checkpoint_sha:
// - If checkpoint_sha: create worktree at that specific commit
// - If include_conversation: inject conversation history into plan
```

**Complexity:** Medium
**Dependencies:** Task 5.2 complete
**Estimated Time:** 3-4 hours

---

## Implementation Summary

### Phase Dependencies

```
Phase 1 (Database)
    └─> Phase 2 (Repository)
            └─> Phase 3 (API Endpoints)
                    └─> Phase 4 (CLI Commands)

Phase 5 (Daemon) can be done in parallel with Phases 3-4
```

### Estimated Total Time

| Phase | Tasks | Estimated Hours |
|-------|-------|-----------------|
| Phase 1: Database Schema | 1 task | 2-3 hours |
| Phase 2: Repository Layer | 2 tasks | 6-8 hours |
| Phase 3: API Endpoints | 3 tasks | 14-17 hours |
| Phase 4: CLI Commands | 2 tasks | 7-9 hours |
| Phase 5: Daemon Integration | 3 tasks | 9-12 hours |
| **Total** | **11 tasks** | **38-49 hours** |

### Task Breakdown by Complexity

| Complexity | Count | Tasks |
|------------|-------|-------|
| Simple | 1 | Phase 1 Migration |
| Medium | 6 | Models, History Endpoints, CLI History, CLI Resume, Protocol, Checkpoint Enhancement |
| Complex | 4 | Repository Functions, Resume Endpoints, Rewind/Fork Endpoints, Daemon Handlers |

### Files to Create

1. `makima/migrations/20250117000000_history_tables.sql`
2. `makima/src/server/handlers/history.rs`

### Files to Modify

**Database Layer:**
- `makima/src/db/models.rs`
- `makima/src/db/repository.rs`

**API Layer:**
- `makima/src/server/handlers/mod.rs`
- `makima/src/server/handlers/mesh.rs`
- `makima/src/server/handlers/mesh_supervisor.rs`
- `makima/src/server/mod.rs`

**CLI Layer:**
- `makima/src/daemon/cli/mod.rs`
- `makima/src/daemon/cli/contract.rs`
- `makima/src/daemon/cli/supervisor.rs`

**Daemon Layer:**
- `makima/src/daemon/ws/protocol.rs`
- `makima/src/daemon/task/manager.rs`
- `makima/src/daemon/worktree/manager.rs`
- `makima/src/server/handlers/mesh_daemon.rs`

---

## Testing Strategy

### Unit Tests
- Repository functions: CRUD operations for snapshots and events
- Model serialization/deserialization
- Diff parsing functions

### Integration Tests
- API endpoint tests with mock database
- CLI command execution tests
- Daemon command handling tests

### End-to-End Tests
- Complete workflow: Create task -> Checkpoint -> Rewind -> Resume
- Fork workflow: Create task -> Checkpoint -> Fork -> Verify state
- History viewing across contract lifecycle

### Manual Testing Checklist
- [ ] Create conversation snapshot at checkpoint
- [ ] View contract history timeline with filters
- [ ] View task conversation history
- [ ] Resume interrupted supervisor (all modes)
- [ ] Resume task from specific checkpoint
- [ ] Rewind code with branch preservation
- [ ] Rewind conversation to message
- [ ] Fork task from checkpoint
- [ ] CLI commands output correctly formatted

---

## Security Considerations

1. **Owner verification**: All operations verify owner_id authorization
2. **Tool key authentication**: Supervisor operations require valid tool keys
3. **Data isolation**: Users cannot access other users' history
4. **Audit logging**: Log all rewind/fork operations for traceability

## Performance Considerations

1. **Pagination**: All list endpoints support cursor-based pagination
2. **Index usage**: Queries use appropriate indexes (contract_id, task_id, created_at)
3. **Snapshot cleanup**: Implement retention policy for old snapshots
4. **Response limits**: Cap response sizes for conversation history