Overcut automatically manages agent sessions to ensure your workflows continue running efficiently. When sessions run too long or get stuck, Overcut uses a two-phase termination system to gracefully close them while preserving your work.

​
How It Works

​
Phase 1: Graceful Termination

When a session reaches its natural end (completes its task, hits time limits, or receives a user signal), Overcut sends a termination request and gives the agent time to:
  • Save any work in progress
  • Upload completed files or artifacts
  • Clean up temporary resources
  • Exit gracefully

​
Phase 2: Forced Termination

If an agent doesn’t respond to the graceful termination request within the configured timeout period, Overcut forces the session to close immediately. This prevents stuck sessions from blocking your workflows.

​
Session States

Overcut tracks sessions through several states:
  • Running: Session is actively working on a task
  • InSession: Agent is in an interactive session (e.g., coding, debugging)
  • WaitingForReply: Session is waiting for user input or comments
  • Terminating: Session has received termination request and is shutting down
  • Completed: Session finished successfully
  • Failed: Session encountered an error or was forced to terminate

​
Configuration

Overcut automatically manages session timeouts to keep your workflows running smoothly. There are two types of timeouts:

​
Session Termination Timeout

  • Default: 5 minutes for agents to gracefully shut down
  • Purpose: Gives agents time to save work, upload files, and clean up resources
  • When it applies: When a session is being terminated (either naturally or by user request)

​
User Response Grace Period

  • Default: 10 minutes for users to respond to session requests
  • Purpose: Allows time for human review and comments before session closes
  • When it applies: When a session is waiting for user input or comments

​
Workflow-Level Timeouts

You can also set a maximum execution time for entire workflows:
  • Range: 30 seconds to 1 hour
  • Purpose: Prevents workflows from running indefinitely
  • How to set: Configure in your workflow definition (contact your administrator for help)

​
What Happens During Termination

​
Session Termination

  1. Overcut sends a termination request to the agent
  2. Agent receives the request and begins shutdown procedures
  3. Agent has 5 minutes to complete cleanup (save files, upload artifacts, etc.)
  4. If successful, session closes normally

​
Forced Session Termination

  1. If the agent doesn’t respond within 5 minutes, Overcut forces immediate termination
  2. Agent must exit immediately (no additional cleanup time)
  3. Session is marked as failed
  4. Workflow continues with the next step

​
Workflow Execution Timeout

  • If a workflow exceeds its configured timeout (30 seconds to 1 hour), it’s automatically marked as “Timeout”
  • This prevents workflows from running indefinitely and consuming resources
  • Timeout status is tracked separately from session termination

​
Best Practices

  • Set realistic timeouts: Don’t set extremely long timeouts unless necessary
  • Monitor session patterns: Watch for sessions that frequently timeout
  • Use appropriate session types: Choose between interactive sessions and task execution based on your needs

​
Troubleshooting

​
Common Issues

​
Monitoring

Overcut provides visibility into session and workflow behavior through:
  • Session status updates: Real-time status changes in the UI (Running, InSession, WaitingForReply, Terminating, Completed, Failed)
  • Workflow execution status: Track workflow progress (Running, Completed, Failed, Timeout)
  • Termination events: Logs showing when and why sessions terminate
  • Execution duration: Monitor how long workflows and individual steps take to complete