Graceful Cancellation

Graceful Cancellation#

MassGen supports graceful cancellation, allowing you to interrupt a running session (Ctrl+C) while still preserving partial progress. This is useful when agents are going down the wrong path or taking too long.

How It Works#

When you press Ctrl+C during coordination:

  1. MassGen captures the current state from all agents

  2. Any answers that have been generated are saved

  3. Agent workspaces are preserved

  4. The session can be resumed later with --continue

# Running a session
$ massgen --config my_config.yaml "Complex question..."

🤖 Multi-Agent
Agents: agent_a, agent_b
Question: Complex question...

[Agent coordination in progress...]

^C
⚠️  Cancellation requested - saving partial progress...
✅ Partial progress saved. Session can be resumed with --continue
👋 Goodbye!

What Gets Saved#

When you cancel mid-session, MassGen saves:

  • Partial answers - Any answers that agents have submitted

  • Agent workspaces - All files created or modified by each agent (separately)

  • Turn metadata - Phase, timestamp, and task information

  • Voting state - If voting was in progress

The partial turn is marked as “incomplete” in the session directory.

What the Next Turn Sees#

When you resume a session with an incomplete turn, no information is lost:

Conversation History: All partial answers are combined into a single assistant message with clear attribution. Agents that were still working (have a workspace but no answer yet) get a placeholder:

[INCOMPLETE TURN - Session was cancelled before completion]
[Phase when cancelled: coordinating]

## agent_a's answer (voted for: agent_b):
First agent's partial answer...
[Workspace available at: /path/to/workspace]

## agent_b:
[No answer submitted - agent was still working]
[View workspace for current progress: /path/to/workspace]

Workspaces: All agent workspaces from the incomplete turn are provided as read-only context paths, allowing agents to see what each other was working on. This includes:

  • Agents that submitted partial answers

  • Agents that were still working (created files but no answer yet)

This ensures no files or progress is lost, even from agents that hadn’t finished their response.

Session Directory Structure#

After cancellation, your session directory will contain:

.massgen/sessions/session_20251205_120000/
├── SESSION_SUMMARY.txt           # Updated with incomplete turn info
├── turn_1/                       # Complete previous turn (if any)
│   ├── metadata.json
│   ├── answer.txt
│   └── workspace/
└── turn_2/                       # Incomplete turn
    ├── metadata.json             # status: "incomplete"
    ├── partial_answers.json      # All agent answers
    ├── answer.txt                # Best available answer
    └── workspaces/               # Per-agent workspaces
        ├── agent_a/
        └── agent_b/

Resuming After Cancellation#

Resume your session with the --continue flag:

$ massgen --continue

📚 Restored session with 2 previous turn(s)
   Starting turn 3

⚠️  Previous turn was incomplete (cancelled during coordinating phase)
   Task: Complex question...
   Partial answers saved from: agent_a, agent_b
   The incomplete turn's partial progress is saved in the session directory.

When resuming:

  • MassGen shows you information about the incomplete turn

  • You can ask the same question again or move on to a new one

  • Previous complete turns provide context for agents

  • Partial answers from the cancelled turn are available for review in the session directory

Viewing Partial Results#

You can review the partial answers saved during cancellation:

# View the partial answers
cat .massgen/sessions/session_*/turn_*/partial_answers.json

# View the best partial answer
cat .massgen/sessions/session_*/turn_*/answer.txt

Force Exit#

If you need to exit immediately without saving:

  • First Ctrl+C: Graceful cancellation (saves partial progress)

  • Second Ctrl+C: Force exit (no saving)

Multi-Turn Mode Behavior#

In multi-turn (interactive) sessions, cancellation works slightly differently:

  • First Ctrl+C: Saves partial progress and returns to the prompt

  • Second Ctrl+C: Exits the session entirely

  • Queued runtime fallback prompts persist: If pending runtime-injection text is promoted to a new turn prompt and that turn is cancelled, the prompt is retained in conversation history for subsequent turns

This allows you to cancel a long-running turn without losing your entire session:

$ massgen --config my_config.yaml  # Interactive mode

🤖 Multi-Agent Session

> What is the meaning of life?

[Agent coordination in progress...]

^C
⚠️  Cancellation requested - saving partial progress...
✅ Partial progress saved. Session can be resumed with --continue
⏸️  Turn cancelled. Partial progress saved.
Enter your next question or /quit to exit.

> Let's try a simpler question...

This behavior ensures you can:

  • Cancel a turn that’s taking too long without losing the session

  • Review partial progress and decide how to proceed

  • Continue with a different question if needed

Use Cases#

Graceful cancellation is helpful when:

  1. Wrong Direction - Agents are pursuing an incorrect approach

  2. Too Long - Coordination is taking longer than expected

  3. Debugging - You want to inspect partial state

  4. Resource Management - You need to free up API calls or compute

Configuration#

Graceful cancellation is enabled by default. No configuration is required.

Note

Partial progress is only saved if at least one agent has submitted an answer. If cancelled before any answers are generated, only the task metadata is saved.