[P1] Implement Project.pause() with flash save mechanism

[frankbria]

Overview

The Project.pause() method needs to implement flash save to preserve context before pausing execution.

Current State

File: codeframe/core/project.py lines 69-71

def pause(self) -> None:
    """Pause project execution."""
    # TODO: Implement flash save before pause
    self._status = ProjectStatus.PAUSED

Expected Behavior

• Trigger flash save to create checkpoint
• Archive COLD tier context items
• Save current agent states
• Update project status to PAUSED
• Persist pause timestamp
• Broadcast project_paused event

Implementation Requirements

1. Call WorkerAgent.flash_save() for each active agent
2. Create checkpoint via CheckpointManager
3. Archive context items with tier=COLD
4. Update project status in database
5. Record pause timestamp for resume calculation
6. Broadcast WebSocket event

Acceptance Criteria

• Flash save creates checkpoint before pause
• COLD context items archived correctly
• Project status updated to PAUSED
• Resume can restore from paused state
• No context loss during pause/resume cycle
• WebSocket event notifies clients

Priority

P1 - Critical: Required for long-running projects that need to pause.

References

• Flash save docs: CLAUDE.md lines 100-109
• Issues Analysis: CODEFRAME_ISSUES_ANALYSIS.md lines 106-113

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

_{You can configure auto-planning by selecting labels in the issue_enrichment configuration.}

🔗 Similar Issues

Related Issues

• [P1] Implement WorkerAgent.execute_task() with Anthropic API integration #98
• [P1] Implement LeadAgent.assign_task() logic #100

👤 Suggested Assignees

• frankbria

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[traycerai]

Plan

Observations

The Project.pause() method in file:codeframe/core/project.py (lines 68-72) is currently a stub with a TODO comment. The codebase has a well-established flash save mechanism in file:codeframe/lib/context_manager.py, checkpoint system in file:codeframe/lib/checkpoint_manager.py, and WebSocket broadcasting infrastructure in file:codeframe/ui/websocket_broadcasts.py. The database has an update_project() method that can update project status, and the ProjectStatus.PAUSED enum value already exists in file:codeframe/core/models.py.

Approach

The implementation will integrate existing flash save and checkpoint mechanisms into the pause() method. The approach follows the established pattern: iterate through active agents, trigger flash saves, create a checkpoint, update project status in the database, and broadcast a WebSocket event. This leverages the existing infrastructure without introducing new complexity, ensuring consistency with the resume mechanism already implemented in Project.resume().

Implementation Steps

1. Update Project.pause() Method

File: file:codeframe/core/project.py (lines 68-72)

Replace the TODO implementation with the following logic:

1. Get project ID from database: Query the database to retrieve the project ID using the project name from config
2. Get active agents: Query Database.get_agents_for_project(project_id, active_only=True) to retrieve all agents currently assigned to the project
3. Trigger flash save for each agent: For each active agent:
   • Instantiate a WorkerAgent with the agent's ID and database connection
   • Call await agent.flash_save() to create a checkpoint and archive COLD tier context items
   • Handle any exceptions gracefully (log errors but continue with other agents)
4. Create project-level checkpoint: Use CheckpointManager to create a comprehensive checkpoint:
   • Initialize CheckpointManager(db=self.db, project_root=self.project_dir, project_id=project_id)
   • Call create_checkpoint(name="Project paused", description="Automatic checkpoint before pause", trigger="pause")
5. Update project status: Call self.db.update_project(project_id, {"status": ProjectStatus.PAUSED, "paused_at": datetime.now(timezone.utc).isoformat()})
6. Broadcast WebSocket event: Import manager from file:codeframe/ui/shared.py and broadcast:

   await manager.broadcast({
       "type": "project_paused",
       "project_id": project_id,
       "timestamp": datetime.now(timezone.utc).isoformat()
   })

7. Update internal status: Set self._status = ProjectStatus.PAUSED
8. Print confirmation: Display user-friendly message with checkpoint details

2. Add Database Schema Support for Pause Timestamp

File: file:codeframe/persistence/database.py

Add paused_at column to the projects table if it doesn't already exist:

1. Create a new migration file in file:codeframe/persistence/migrations/ following the existing pattern
2. Add migration to add paused_at TIMESTAMP NULL column to projects table
3. Update the _create_schema() method to include paused_at in the initial schema for new installations

3. Add WebSocket Event Handler (Optional Enhancement)

File: file:codeframe/ui/websocket_broadcasts.py

Add a dedicated broadcast function for project pause events:

async def broadcast_project_paused(
    manager,
    project_id: int,
    checkpoint_id: int,
    agents_saved: int,
) -> None:
    """Broadcast project pause event to connected clients."""

This function should:

• Accept the ConnectionManager, project_id, checkpoint_id, and count of agents that were flash-saved
• Create a message with type "project_paused" including metadata
• Call manager.broadcast(message) with error handling

4. Update Project.resume() Integration

File: file:codeframe/core/project.py (lines 74-128)

Verify the resume() method properly handles paused projects:

1. Check that it retrieves the most recent checkpoint (already implemented)
2. Ensure it restores context for all agents that were active when paused
3. Update project status from PAUSED to ACTIVE
4. Clear the paused_at timestamp when resuming

5. Error Handling and Validation

Add robust error handling throughout:

1. Database not initialized: Raise RuntimeError if self.db is None
2. No active agents: Handle gracefully (create checkpoint but skip agent flash saves)
3. Flash save failures: Log errors but continue with other agents
4. Checkpoint creation failure: Raise exception and don't update status
5. WebSocket broadcast failure: Log warning but don't block pause operation

6. Testing Considerations

While not writing tests, ensure the implementation supports:

1. Unit tests: Mock database, agents, and checkpoint manager
2. Integration tests: Test full pause/resume cycle with real database
3. Edge cases: Empty project, no agents, failed flash saves
4. Performance: Measure time for pause operation with multiple agents

Sequence Diagram

sequenceDiagram
    participant User
    participant Project
    participant Database
    participant WorkerAgent
    participant ContextManager
    participant CheckpointManager
    participant WebSocket

    User->>Project: pause()
    Project->>Database: Get project_id
    Database-->>Project: project_id
    Project->>Database: get_agents_for_project(project_id)
    Database-->>Project: List of active agents
    
    loop For each agent
        Project->>WorkerAgent: flash_save()
        WorkerAgent->>ContextManager: flash_save(project_id, agent_id)
        ContextManager->>Database: Archive COLD tier items
        ContextManager->>Database: Create checkpoint
        ContextManager-->>WorkerAgent: Flash save result
        WorkerAgent-->>Project: Success
    end
    
    Project->>CheckpointManager: create_checkpoint("Project paused")
    CheckpointManager->>Database: Save checkpoint metadata
    CheckpointManager-->>Project: Checkpoint created
    
    Project->>Database: update_project(status=PAUSED, paused_at=now)
    Database-->>Project: Success
    
    Project->>WebSocket: broadcast(project_paused event)
    WebSocket-->>User: Real-time notification
    
    Project-->>User: "⏸️ Project paused"

Loading

Key Files Reference

File	Purpose
file:codeframe/core/project.py	Main implementation location (lines 68-72)
file:codeframe/lib/context_manager.py	Flash save mechanism (flash_save() method)
file:codeframe/lib/checkpoint_manager.py	Checkpoint creation and restoration
file:codeframe/persistence/database.py	Database operations (update_project(), get_agents_for_project())
file:codeframe/ui/websocket_broadcasts.py	WebSocket event broadcasting
file:codeframe/ui/shared.py	ConnectionManager for WebSocket
file:codeframe/core/models.py	ProjectStatus enum and data models

Dependencies

The implementation requires:

• datetime and timezone from Python standard library
• asyncio for async operations
• Existing WorkerAgent, ContextManager, CheckpointManager classes
• Database connection (self.db)
• WebSocket ConnectionManager from file:codeframe/ui/shared.py

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `Project.pause()` method in `file:codeframe/core/project.py` (lines 68-72) is currently a stub with a TODO comment. The codebase has a well-established flash save mechanism in `file:codeframe/lib/context_manager.py`, checkpoint system in `file:codeframe/lib/checkpoint_manager.py`, and WebSocket broadcasting infrastructure in `file:codeframe/ui/websocket_broadcasts.py`. The database has an `update_project()` method that can update project status, and the `ProjectStatus.PAUSED` enum value already exists in `file:codeframe/core/models.py`.

## Approach

The implementation will integrate existing flash save and checkpoint mechanisms into the `pause()` method. The approach follows the established pattern: iterate through active agents, trigger flash saves, create a checkpoint, update project status in the database, and broadcast a WebSocket event. This leverages the existing infrastructure without introducing new complexity, ensuring consistency with the resume mechanism already implemented in `Project.resume()`.

## Implementation Steps

### 1. Update Project.pause() Method

**File**: `file:codeframe/core/project.py` (lines 68-72)

Replace the TODO implementation with the following logic:

1. **Get project ID from database**: Query the database to retrieve the project ID using the project name from config
2. **Get active agents**: Query `Database.get_agents_for_project(project_id, active_only=True)` to retrieve all agents currently assigned to the project
3. **Trigger flash save for each agent**: For each active agent:
   - Instantiate a `WorkerAgent` with the agent's ID and database connection
   - Call `await agent.flash_save()` to create a checkpoint and archive COLD tier context items
   - Handle any exceptions gracefully (log errors but continue with other agents)
4. **Create project-level checkpoint**: Use `CheckpointManager` to create a comprehensive checkpoint:
   - Initialize `CheckpointManager(db=self.db, project_root=self.project_dir, project_id=project_id)`
   - Call `create_checkpoint(name="Project paused", description="Automatic checkpoint before pause", trigger="pause")`
5. **Update project status**: Call `self.db.update_project(project_id, {"status": ProjectStatus.PAUSED, "paused_at": datetime.now(timezone.utc).isoformat()})`
6. **Broadcast WebSocket event**: Import `manager` from `file:codeframe/ui/shared.py` and broadcast:
   ```python
   await manager.broadcast({
       "type": "project_paused",
       "project_id": project_id,
       "timestamp": datetime.now(timezone.utc).isoformat()
   })
   ```
7. **Update internal status**: Set `self._status = ProjectStatus.PAUSED`
8. **Print confirmation**: Display user-friendly message with checkpoint details

### 2. Add Database Schema Support for Pause Timestamp

**File**: `file:codeframe/persistence/database.py`

Add `paused_at` column to the `projects` table if it doesn't already exist:

1. Create a new migration file in `file:codeframe/persistence/migrations/` following the existing pattern
2. Add migration to add `paused_at TIMESTAMP NULL` column to `projects` table
3. Update the `_create_schema()` method to include `paused_at` in the initial schema for new installations

### 3. Add WebSocket Event Handler (Optional Enhancement)

**File**: `file:codeframe/ui/websocket_broadcasts.py`

Add a dedicated broadcast function for project pause events:

```python
async def broadcast_project_paused(
    manager,
    project_id: int,
    checkpoint_id: int,
    agents_saved: int,
) -> None:
    """Broadcast project pause event to connected clients."""
```

This function should:
- Accept the ConnectionManager, project_id, checkpoint_id, and count of agents that were flash-saved
- Create a message with type `"project_paused"` including metadata
- Call `manager.broadcast(message)` with error handling

### 4. Update Project.resume() Integration

**File**: `file:codeframe/core/project.py` (lines 74-128)

Verify the `resume()` method properly handles paused projects:

1. Check that it retrieves the most recent checkpoint (already implemented)
2. Ensure it restores context for all agents that were active when paused
3. Update project status from PAUSED to ACTIVE
4. Clear the `paused_at` timestamp when resuming

### 5. Error Handling and Validation

Add robust error handling throughout:

1. **Database not initialized**: Raise `RuntimeError` if `self.db` is None
2. **No active agents**: Handle gracefully (create checkpoint but skip agent flash saves)
3. **Flash save failures**: Log errors but continue with other agents
4. **Checkpoint creation failure**: Raise exception and don't update status
5. **WebSocket broadcast failure**: Log warning but don't block pause operation

### 6. Testing Considerations

While not writing tests, ensure the implementation supports:

1. **Unit tests**: Mock database, agents, and checkpoint manager
2. **Integration tests**: Test full pause/resume cycle with real database
3. **Edge cases**: Empty project, no agents, failed flash saves
4. **Performance**: Measure time for pause operation with multiple agents

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant Project
    participant Database
    participant WorkerAgent
    participant ContextManager
    participant CheckpointManager
    participant WebSocket

    User->>Project: pause()
    Project->>Database: Get project_id
    Database-->>Project: project_id
    Project->>Database: get_agents_for_project(project_id)
    Database-->>Project: List of active agents
    
    loop For each agent
        Project->>WorkerAgent: flash_save()
        WorkerAgent->>ContextManager: flash_save(project_id, agent_id)
        ContextManager->>Database: Archive COLD tier items
        ContextManager->>Database: Create checkpoint
        ContextManager-->>WorkerAgent: Flash save result
        WorkerAgent-->>Project: Success
    end
    
    Project->>CheckpointManager: create_checkpoint("Project paused")
    CheckpointManager->>Database: Save checkpoint metadata
    CheckpointManager-->>Project: Checkpoint created
    
    Project->>Database: update_project(status=PAUSED, paused_at=now)
    Database-->>Project: Success
    
    Project->>WebSocket: broadcast(project_paused event)
    WebSocket-->>User: Real-time notification
    
    Project-->>User: "⏸️ Project paused"
```

## Key Files Reference

| File | Purpose |
|------|---------|
| `file:codeframe/core/project.py` | Main implementation location (lines 68-72) |
| `file:codeframe/lib/context_manager.py` | Flash save mechanism (`flash_save()` method) |
| `file:codeframe/lib/checkpoint_manager.py` | Checkpoint creation and restoration |
| `file:codeframe/persistence/database.py` | Database operations (`update_project()`, `get_agents_for_project()`) |
| `file:codeframe/ui/websocket_broadcasts.py` | WebSocket event broadcasting |
| `file:codeframe/ui/shared.py` | ConnectionManager for WebSocket |
| `file:codeframe/core/models.py` | ProjectStatus enum and data models |

## Dependencies

The implementation requires:
- `datetime` and `timezone` from Python standard library
- `asyncio` for async operations
- Existing `WorkerAgent`, `ContextManager`, `CheckpointManager` classes
- Database connection (`self.db`)
- WebSocket ConnectionManager from `file:codeframe/ui/shared.py`

---

Execution Information

Branch: main
Commit: 1a87e4e

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[frankbria]

Closed by PR #130