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

# Resume and History System Specification

## Overview

This specification defines a comprehensive system for viewing historical conversation data, resuming interrupted work, and rewinding/restoring to previous states in the Makima platform. The system integrates with the existing contract, task, supervisor, and checkpoint infrastructure.

## Table of Contents

1. [Current Infrastructure](#1-current-infrastructure)
2. [History Viewing Features](#2-history-viewing-features)
3. [Resume System](#3-resume-system)
4. [Rewind/Restore Features](#4-rewindrestore-features)
5. [Integration Points](#5-integration-points)
6. [Implementation Plan](#6-implementation-plan)

---

## 1. Current Infrastructure

### 1.1 Existing Database Tables

The system builds upon these existing tables:

#### `supervisor_states`
```sql
- id: UUID
- contract_id: UUID
- task_id: UUID
- conversation_history: JSONB  -- Full Claude conversation history
- last_checkpoint_id: UUID
- pending_task_ids: UUID[]
- phase: VARCHAR
- last_activity: TIMESTAMP
- created_at: TIMESTAMP
- updated_at: TIMESTAMP
```

#### `task_checkpoints`
```sql
- id: UUID
- task_id: UUID
- checkpoint_number: INT
- commit_sha: VARCHAR
- branch_name: VARCHAR
- message: VARCHAR
- files_changed: JSONB  -- [{path, action: 'A'|'M'|'D'}]
- lines_added: INT
- lines_removed: INT
- created_at: TIMESTAMP
```

#### `task_events`
```sql
- id: UUID
- task_id: UUID
- event_type: VARCHAR  -- 'output', 'status_change', etc.
- previous_status: VARCHAR
- new_status: VARCHAR
- event_data: JSONB  -- Contains full output data
- created_at: TIMESTAMP
```

#### `tasks` (relevant fields)
```sql
- conversation_state: JSONB  -- Saved conversation context
- continue_from_task_id: UUID  -- For worktree inheritance
- last_checkpoint_sha: VARCHAR
- checkpoint_count: INT
- checkpoint_message: VARCHAR
```

#### `mesh_chat_conversations` / `mesh_chat_messages`
```sql
-- Conversations for mesh chat
- id, owner_id, name, is_active, created_at, updated_at

-- Messages
- id, conversation_id, role, content, context_type, context_task_id
- tool_calls: JSONB, pending_questions: JSONB, created_at
```

#### `contract_chat_conversations` / `contract_chat_messages`
```sql
-- Similar structure to mesh chat, scoped to contracts
```

### 1.2 Existing Repository Functions

```rust
// Checkpoint functions
- list_task_checkpoints(pool, task_id) -> Vec<TaskCheckpoint>
- get_task_checkpoint(pool, id) -> Option<TaskCheckpoint>
- get_task_checkpoint_by_sha(pool, commit_sha) -> Option<TaskCheckpoint>

// Supervisor state functions
- upsert_supervisor_state(pool, contract_id, task_id, conversation_history, pending_task_ids, phase)
- get_supervisor_state(pool, contract_id) -> Option<SupervisorState>
- get_supervisor_state_by_task(pool, task_id) -> Option<SupervisorState>
- update_supervisor_conversation(pool, contract_id, conversation_history)
- update_supervisor_pending_tasks(pool, contract_id, pending_task_ids)

// Task output functions
- get_task_output(pool, task_id, limit) -> Vec<TaskEvent>
- list_task_events(pool, task_id, limit) -> Vec<TaskEvent>
```

### 1.3 Existing API Endpoints

```
GET  /api/v1/mesh/tasks/{id}/output         -- Task output history
GET  /api/v1/mesh/tasks/{id}/events         -- Task events
GET  /api/v1/mesh/tasks/{id}/checkpoints    -- List checkpoints
POST /api/v1/mesh/tasks/{id}/continue       -- Continue interrupted task
POST /api/v1/mesh/tasks/{id}/reassign       -- Reassign to new daemon
```

---

## 2. History Viewing Features

### 2.1 Contract History Timeline

View all activities across a contract's lifecycle, aggregating data from all phases and tasks.

#### API Endpoint

```
GET /api/v1/contracts/{contract_id}/history
```

#### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `phase` | string | Filter by phase (research, specify, plan, execute, review) |
| `event_types` | string[] | Filter by event types (task_created, task_completed, checkpoint, phase_change, chat) |
| `from` | datetime | Start of time range |
| `to` | datetime | End of time range |
| `limit` | int | Max results (default: 100) |
| `cursor` | string | Pagination cursor |

#### Response Schema

```typescript
interface ContractHistoryResponse {
  contractId: string;
  entries: HistoryEntry[];
  totalCount: number;
  cursor?: string;
}

interface HistoryEntry {
  id: string;
  timestamp: datetime;
  entryType: 'task_event' | 'chat_message' | 'phase_change' | 'checkpoint' | 'file_change';
  phase: string;

  // Task event data (when entryType = 'task_event')
  taskId?: string;
  taskName?: string;
  eventType?: string;
  eventData?: any;

  // Chat message data (when entryType = 'chat_message')
  conversationId?: string;
  role?: string;
  content?: string;

  // Checkpoint data (when entryType = 'checkpoint')
  checkpointNumber?: number;
  commitSha?: string;
  message?: string;
  filesChanged?: FileChange[];

  // Phase change data (when entryType = 'phase_change')
  previousPhase?: string;
  newPhase?: string;
}
```

### 2.2 Task Conversation History

View the complete conversation history for a specific task.

#### API Endpoint

```
GET /api/v1/mesh/tasks/{task_id}/conversation
```

#### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `include_tool_calls` | bool | Include tool call details (default: true) |
| `include_tool_results` | bool | Include tool results (default: true) |
| `limit` | int | Max messages (default: all) |

#### Response Schema

```typescript
interface TaskConversationResponse {
  taskId: string;
  taskName: string;
  status: string;
  messages: ConversationMessage[];
  totalTokens?: number;
  totalCost?: number;
}

interface ConversationMessage {
  id: string;
  role: 'user' | 'assistant' | 'system' | 'tool';
  content: string;
  timestamp: datetime;

  // For assistant messages
  toolCalls?: ToolCall[];

  // For tool messages
  toolName?: string;
  toolInput?: any;
  toolResult?: string;
  isError?: boolean;

  // Cost tracking
  tokenCount?: number;
  costUsd?: number;
}
```

### 2.3 Supervisor Conversation History

View the full conversation history for a contract's supervisor.

#### API Endpoint

```
GET /api/v1/contracts/{contract_id}/supervisor/conversation
```

#### Response Schema

```typescript
interface SupervisorConversationResponse {
  contractId: string;
  supervisorTaskId: string;
  phase: string;
  lastActivity: datetime;
  pendingTaskIds: string[];

  // Full conversation from supervisor_states.conversation_history
  messages: ConversationMessage[];

  // Tasks spawned during conversation
  spawnedTasks: TaskReference[];
}

interface TaskReference {
  taskId: string;
  taskName: string;
  status: string;
  createdAt: datetime;
  completedAt?: datetime;
}
```

### 2.4 Checkpoint History with Diffs

View checkpoint history with Git diff information.

#### API Endpoint

```
GET /api/v1/mesh/tasks/{task_id}/checkpoints/{checkpoint_id}/diff
```

#### Response Schema

```typescript
interface CheckpointDiffResponse {
  checkpoint: TaskCheckpoint;
  diff: GitDiff;
  previousCheckpoint?: TaskCheckpoint;
}

interface GitDiff {
  files: FileDiff[];
  stats: {
    filesChanged: number;
    insertions: number;
    deletions: number;
  };
}

interface FileDiff {
  path: string;
  action: 'added' | 'modified' | 'deleted';
  additions: number;
  deletions: number;
  hunks: DiffHunk[];
}
```

### 2.5 Activity Timeline View

Unified timeline showing all activities for a contract or task.

#### API Endpoint

```
GET /api/v1/timeline
```

#### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `contract_id` | UUID | Filter by contract |
| `task_id` | UUID | Filter by specific task |
| `include_subtasks` | bool | Include subtask activities |
| `from` | datetime | Start of time range |
| `to` | datetime | End of time range |

---

## 3. Resume System

### 3.1 Resume Interrupted Supervisor

Resume a supervisor conversation that was interrupted (daemon disconnect, crash, etc.).

#### API Endpoint

```
POST /api/v1/contracts/{contract_id}/supervisor/resume
```

#### Request Schema

```typescript
interface ResumeSupervisorRequest {
  // Optional: specify daemon to resume on
  targetDaemonId?: string;

  // How to handle the resume
  resumeMode: 'continue' | 'restart_phase' | 'from_checkpoint';

  // For 'from_checkpoint' mode
  checkpointId?: string;

  // Additional context to inject
  additionalContext?: string;
}
```

#### Behavior

1. **continue** (default):
   - Load `supervisor_states.conversation_history`
   - Prepend context summary to prompt
   - Resume with full conversation context

2. **restart_phase**:
   - Start fresh for current phase
   - Keep knowledge of completed work
   - Don't replay old conversation

3. **from_checkpoint**:
   - Reset code to checkpoint state
   - Clear conversation after checkpoint
   - Resume from clean state

#### Response Schema

```typescript
interface ResumeSupervisorResponse {
  supervisorTaskId: string;
  daemonId: string;
  resumedFrom: {
    phase: string;
    lastActivity: datetime;
    messageCount: number;
  };
  status: 'starting' | 'running';
}
```

### 3.2 Resume Interrupted Task

Resume a task that was interrupted mid-execution.

#### API Endpoint (existing, enhanced)

```
POST /api/v1/mesh/tasks/{task_id}/continue
```

#### Enhanced Request Schema

```typescript
interface ContinueTaskRequest {
  targetDaemonId?: string;

  // NEW: Resume options
  resumeMode?: 'with_context' | 'clean_restart' | 'from_checkpoint';
  checkpointSha?: string;

  // NEW: Context control
  contextOptions?: {
    maxMessages?: number;  // Limit context size
    includeToolCalls?: boolean;
    includeToolResults?: boolean;
    summaryMode?: boolean;  // Use summarized context
  };
}
```

### 3.3 Resume from Specific Checkpoint

Create a new task that starts from a specific checkpoint's code state.

#### API Endpoint

```
POST /api/v1/mesh/tasks/{task_id}/checkpoints/{checkpoint_id}/resume
```

#### Request Schema

```typescript
interface ResumeFromCheckpointRequest {
  // Name for the new task
  taskName?: string;

  // Plan/instructions for the resumed task
  plan: string;

  // Whether to include conversation context up to checkpoint
  includeConversation?: boolean;

  // Target daemon
  targetDaemonId?: string;
}
```

#### Behavior

1. Get checkpoint's commit SHA
2. Create new task with `checkpoint_sha` set
3. When daemon spawns task:
   - Create worktree at checkpoint commit
   - Optionally include conversation context
4. Task starts from checkpoint's code state

#### Response Schema

```typescript
interface ResumeFromCheckpointResponse {
  newTaskId: string;
  sourceTaskId: string;
  checkpointUsed: {
    number: number;
    sha: string;
    message: string;
  };
  status: 'pending' | 'starting';
}
```

### 3.4 Continue from Previous Task State

Use existing `continue_from_task_id` field to inherit worktree state.

#### API Endpoint (existing)

```
POST /api/v1/mesh/tasks
```

#### Relevant Fields

```typescript
interface CreateTaskRequest {
  // ... other fields ...

  // Copy worktree from this task
  continueFromTaskId?: string;

  // Specific checkpoint SHA to branch from
  checkpointSha?: string;

  // Files to copy from parent task's worktree
  copyFiles?: string[];
}
```

---

## 4. Rewind/Restore Features

### 4.1 Rewind Code to Checkpoint

Restore a task's worktree to a specific checkpoint's state.

#### API Endpoint

```
POST /api/v1/mesh/tasks/{task_id}/rewind
```

#### Request Schema

```typescript
interface RewindTaskRequest {
  // Target checkpoint to rewind to
  checkpointId?: string;
  checkpointSha?: string;  // Alternative: use SHA directly

  // What to do with current state
  preserveMode: 'discard' | 'create_branch' | 'stash';

  // For 'create_branch' mode
  branchName?: string;
}
```

#### Behavior

1. **discard**: Hard reset to checkpoint, lose current changes
2. **create_branch**: Create branch from current HEAD, then reset
3. **stash**: Git stash current changes, then reset

#### Response Schema

```typescript
interface RewindTaskResponse {
  taskId: string;
  rewindedTo: {
    checkpointNumber: number;
    sha: string;
    message: string;
  };
  preservedAs?: {
    type: 'branch' | 'stash';
    reference: string;  // Branch name or stash ref
  };
}
```

### 4.2 Rewind Conversation to Point

Truncate conversation history to a specific point.

#### API Endpoint

```
POST /api/v1/contracts/{contract_id}/supervisor/conversation/rewind
```

#### Request Schema

```typescript
interface RewindConversationRequest {
  // Rewind to message with this ID
  toMessageId?: string;

  // OR rewind to messages before this timestamp
  toTimestamp?: datetime;

  // OR rewind by N messages
  byMessageCount?: number;

  // Whether to also rewind code to matching checkpoint
  rewindCode?: boolean;
}
```

#### Behavior

1. Identify the target point in `supervisor_states.conversation_history`
2. Truncate messages after that point
3. If `rewindCode` is true and there's a matching checkpoint, reset code
4. Update `supervisor_states` with truncated history

### 4.3 Fork from Historical Point

Create a new task/conversation branch from any point in history.

#### API Endpoint

```
POST /api/v1/mesh/tasks/{task_id}/fork
```

#### Request Schema

```typescript
interface ForkTaskRequest {
  // Fork point specification
  forkFrom: {
    type: 'checkpoint' | 'timestamp' | 'message_id';
    value: string;
  };

  // New task configuration
  newTask: {
    name: string;
    plan: string;
    includeConversation?: boolean;  // Include history up to fork point
  };

  // Git branching options
  branchOptions?: {
    createBranch?: boolean;
    branchName?: string;
  };
}
```

#### Behavior

1. Identify the fork point (checkpoint, timestamp, or message)
2. Create new task with:
   - `checkpoint_sha` from fork point (or nearest checkpoint)
   - Conversation context up to fork point (if requested)
3. Create git branch if requested
4. Start task in new direction

#### Response Schema

```typescript
interface ForkTaskResponse {
  newTaskId: string;
  sourceTaskId: string;
  forkPoint: {
    type: string;
    checkpoint?: TaskCheckpoint;
    timestamp: datetime;
  };
  branchName?: string;
  conversationIncluded: boolean;
  messageCount?: number;
}
```

### 4.4 Create Branch from Checkpoint

Create a new git branch from a specific checkpoint without starting a task.

#### API Endpoint

```
POST /api/v1/mesh/tasks/{task_id}/checkpoints/{checkpoint_id}/branch
```

#### Request Schema

```typescript
interface CreateBranchFromCheckpointRequest {
  branchName: string;
  checkout?: boolean;  // Whether to checkout the new branch
}
```

---

## 5. Integration Points

### 5.1 New CLI Commands

#### History Commands

```bash
# View contract history timeline
makima contract history [--phase <phase>] [--from <date>] [--to <date>]

# View task conversation history
makima task history <task_id> [--limit <n>] [--no-tool-calls]

# View task checkpoints
makima task checkpoints <task_id> [--with-diff]

# View specific checkpoint diff
makima task checkpoint-diff <task_id> <checkpoint_number>
```

#### Resume Commands

```bash
# Resume supervisor
makima supervisor resume [--mode <continue|restart|checkpoint>] [--checkpoint <id>]

# Resume task
makima task resume <task_id> [--mode <context|clean|checkpoint>] [--checkpoint <sha>]

# Resume from checkpoint
makima task resume-from <task_id> --checkpoint <number> --plan "continue with..."
```

#### Rewind Commands

```bash
# Rewind code to checkpoint
makima task rewind <task_id> --checkpoint <number> [--preserve-branch <name>]

# Rewind conversation
makima supervisor rewind-conversation --to-message <id> [--rewind-code]

# Fork from checkpoint
makima task fork <task_id> --checkpoint <number> --name "alternate approach" --plan "..."
```

### 5.2 New API Endpoints Summary

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/contracts/{id}/history` | Contract history timeline |
| GET | `/api/v1/contracts/{id}/supervisor/conversation` | Supervisor conversation |
| POST | `/api/v1/contracts/{id}/supervisor/resume` | Resume supervisor |
| POST | `/api/v1/contracts/{id}/supervisor/conversation/rewind` | Rewind conversation |
| GET | `/api/v1/mesh/tasks/{id}/conversation` | Task conversation |
| GET | `/api/v1/mesh/tasks/{id}/checkpoints/{cid}/diff` | Checkpoint diff |
| POST | `/api/v1/mesh/tasks/{id}/checkpoints/{cid}/resume` | Resume from checkpoint |
| POST | `/api/v1/mesh/tasks/{id}/checkpoints/{cid}/branch` | Branch from checkpoint |
| POST | `/api/v1/mesh/tasks/{id}/rewind` | Rewind task code |
| POST | `/api/v1/mesh/tasks/{id}/fork` | Fork from history |
| GET | `/api/v1/timeline` | Unified timeline |

### 5.3 Database Schema Changes

#### New Table: `conversation_snapshots`

Store conversation state at specific points for rewind capability.

```sql
CREATE TABLE 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 INT NOT NULL,
    conversation_state JSONB NOT NULL,  -- Full conversation at this point
    metadata JSONB,  -- Additional context
    created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_conversation_snapshots_task ON conversation_snapshots(task_id);
CREATE INDEX idx_conversation_snapshots_checkpoint ON conversation_snapshots(checkpoint_id);
```

#### New Table: `history_events`

Unified event table for timeline views.

```sql
CREATE TABLE 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 type
    phase VARCHAR(50),
    event_data JSONB NOT NULL,
    created_at TIMESTAMPTZ 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);
```

#### Table Modifications

```sql
-- Add to task_checkpoints
ALTER TABLE task_checkpoints ADD COLUMN conversation_snapshot_id UUID
    REFERENCES conversation_snapshots(id) ON DELETE SET NULL;

-- Add to tasks
ALTER TABLE tasks ADD COLUMN forked_from_task_id UUID
    REFERENCES tasks(id) ON DELETE SET NULL;
ALTER TABLE tasks ADD COLUMN forked_at_checkpoint_id UUID
    REFERENCES task_checkpoints(id) ON DELETE SET NULL;
```

### 5.4 Frontend Integration

#### New Components

1. **ContractTimeline** - Visual timeline of contract activities
2. **ConversationViewer** - Display conversation history with syntax highlighting
3. **CheckpointBrowser** - Browse checkpoints with diff view
4. **RewindControls** - UI for rewind operations
5. **ForkDialog** - Modal for forking from history

#### New Routes

```
/contracts/:id/history          - Contract history timeline
/contracts/:id/supervisor       - Supervisor conversation view
/tasks/:id/conversation         - Task conversation view
/tasks/:id/checkpoints          - Checkpoint browser
/tasks/:id/checkpoints/:cid     - Checkpoint detail with diff
```

---

## 6. Implementation Plan

### 6.1 Phase 1: Database & Models (Migration 20250116_history_tables)

**Migrations:**

1. Create `conversation_snapshots` table
2. Create `history_events` table
3. Add columns to `task_checkpoints` and `tasks`
4. Create indexes for efficient queries

**Models (Rust):**

1. `ConversationSnapshot` struct
2. `HistoryEvent` struct
3. `ConversationMessage` struct (unified format)
4. Update `TaskCheckpoint` with new fields

### 6.2 Phase 2: Repository Functions

**New Functions:**

```rust
// Conversation snapshots
pub async fn create_conversation_snapshot(pool, task_id, checkpoint_id, state) -> ConversationSnapshot
pub async fn get_conversation_snapshot(pool, id) -> Option<ConversationSnapshot>
pub async fn get_conversation_at_checkpoint(pool, checkpoint_id) -> Option<ConversationSnapshot>
pub async fn list_conversation_snapshots(pool, task_id) -> Vec<ConversationSnapshot>

// History events
pub async fn record_history_event(pool, event) -> HistoryEvent
pub async fn get_contract_history(pool, contract_id, filters) -> Vec<HistoryEvent>
pub async fn get_task_history(pool, task_id, filters) -> Vec<HistoryEvent>
pub async fn get_timeline(pool, owner_id, filters) -> Vec<HistoryEvent>

// Conversation retrieval
pub async fn get_task_conversation(pool, task_id, options) -> Vec<ConversationMessage>
pub async fn get_supervisor_conversation(pool, contract_id) -> SupervisorConversation

// Checkpoint operations
pub async fn get_checkpoint_diff(pool, checkpoint_id) -> CheckpointDiff
pub async fn create_checkpoint_with_snapshot(pool, task_id, message, conversation_state) -> TaskCheckpoint
```

### 6.3 Phase 3: API Endpoints

**History Endpoints:**

1. `GET /api/v1/contracts/{id}/history`
2. `GET /api/v1/contracts/{id}/supervisor/conversation`
3. `GET /api/v1/mesh/tasks/{id}/conversation`
4. `GET /api/v1/mesh/tasks/{id}/checkpoints/{cid}/diff`
5. `GET /api/v1/timeline`

**Resume Endpoints:**

1. `POST /api/v1/contracts/{id}/supervisor/resume`
2. `POST /api/v1/mesh/tasks/{id}/checkpoints/{cid}/resume`
3. Enhance existing `POST /api/v1/mesh/tasks/{id}/continue`

**Rewind Endpoints:**

1. `POST /api/v1/mesh/tasks/{id}/rewind`
2. `POST /api/v1/contracts/{id}/supervisor/conversation/rewind`
3. `POST /api/v1/mesh/tasks/{id}/fork`
4. `POST /api/v1/mesh/tasks/{id}/checkpoints/{cid}/branch`

### 6.4 Phase 4: CLI Commands

**New Commands:**

1. `makima contract history` - View contract history
2. `makima task history` - View task conversation
3. `makima task checkpoints` - List checkpoints
4. `makima task checkpoint-diff` - View checkpoint diff
5. `makima supervisor resume` - Resume supervisor
6. `makima task resume` - Resume task
7. `makima task resume-from` - Resume from checkpoint
8. `makima task rewind` - Rewind code
9. `makima supervisor rewind-conversation` - Rewind conversation
10. `makima task fork` - Fork from history

### 6.5 Phase 5: Daemon Integration

**New Daemon Commands:**

```rust
enum DaemonCommand {
    // Existing...

    // New
    RewindToCheckpoint {
        task_id: Uuid,
        checkpoint_sha: String,
        preserve_mode: PreserveMode,
        branch_name: Option<String>,
    },
    CreateConversationSnapshot {
        task_id: Uuid,
    },
    RestoreFromSnapshot {
        task_id: Uuid,
        snapshot_id: Uuid,
    },
}
```

**Daemon Handlers:**

1. Implement `handle_rewind_to_checkpoint`
2. Implement `handle_create_conversation_snapshot`
3. Update checkpoint creation to include conversation state
4. Update task spawning to handle fork/resume scenarios

### 6.6 Phase 6: Frontend Components

**Components:**

1. ContractTimeline
2. ConversationViewer
3. CheckpointBrowser
4. DiffViewer
5. RewindControls
6. ForkDialog
7. ResumeDialog

**Routes & Pages:**

1. Contract history page
2. Supervisor conversation page
3. Task conversation page
4. Checkpoint detail page

---

## 7. Security Considerations

### 7.1 Access Control

- All history/resume/rewind operations must verify owner_id
- Supervisor operations require tool key authentication
- Frontend operations require user authentication
- Prevent access to other users' conversation history

### 7.2 Data Retention

- Conversation snapshots may contain sensitive data
- Implement configurable retention policies
- Consider encryption for stored conversation data
- Provide data export/deletion capabilities

### 7.3 Audit Trail

- Log all rewind/restore operations
- Track who initiated changes
- Maintain original data before modifications

---

## 8. Performance Considerations

### 8.1 Pagination

- All list endpoints support cursor-based pagination
- Limit maximum response sizes
- Use efficient queries with proper indexes

### 8.2 Caching

- Cache frequently accessed conversation history
- Invalidate cache on updates
- Consider read replicas for history queries

### 8.3 Storage

- Compress large conversation histories
- Consider archiving old snapshots
- Monitor database size growth

---

## 9. Future Enhancements

1. **Search within history** - Full-text search across conversations
2. **History comparison** - Diff between two points in time
3. **Replay mode** - Step through conversation history
4. **Export history** - Download conversation/checkpoint history
5. **History annotations** - Add notes to historical points
6. **Automatic snapshots** - Periodic conversation backups
7. **History sharing** - Share specific history ranges
8. **AI-powered summaries** - Generate summaries of historical periods