Docs · Execution
Session queue
Sessions are queued per Work item. Only one session can hold the worktree lock at a time. Operators control session lifecycle through pause, resume, and abort.
Queue lifecycle
When a session is submitted for a Work item that already has an active session, it enters the queue. Queue position is FIFO per Work item.
| State | Meaning |
|---|---|
| idle | No session active or queued for this Work item. |
| queued | Session submitted, waiting for the lock to be released. |
| active | Session holds the lock and is executing. |
| paused | Active session has been paused by the operator. Lock is held. |
GET /api/sessions/queue
→ [{ "case_id": "...", "session_id": "...", "position": 1, "status": "queued" }]
GET /api/sessions/active
→ [{ "case_id": "...", "session_id": "...", "started_at": "...", "mode": "WORK" }]Lock contention
The lock is per worktree. A session acquires the lock when it begins executing and releases it on completion, abort, or after a configurable timeout.
GET /api/worktrees/:case_id/lock — check lock status
POST /api/worktrees/:case_id/lock — acquire lock (used internally by sessions)
DELETE /api/worktrees/:case_id/lock — force-release lock (operator override)Force-releasing a lock terminates the active session immediately. Use only when a session is unresponsive — normal completion releases the lock automatically.
Pause vs abort
| Action | Lock | Session log | Can resume? |
|---|---|---|---|
| Pause | Held | Marked paused | Yes — resume continues from current point |
| Abort | Released | Marked aborted | No — a new session must be started |
Pause does not preserve in-flight terminal output from the current step. The session state is saved but live streaming stops immediately.
Resume semantics
A paused session resumes by sending:
POST /api/cases/:id/session/resumeThe session re-acquires the lock, restores context from the session log, and continues execution from the last completed step. The operator can change RunMode or PermMode before resuming.
API reference
| Method | Endpoint | Purpose |
|---|---|---|
GET | /api/sessions/queue | List all queued sessions across all Work items. |
POST | /api/sessions/queue | Add a session to the queue. |
GET | /api/sessions/active | List all active sessions. |
POST | /api/cases/:id/session/pause | Pause the active session for a Work item. |
POST | /api/cases/:id/session/resume | Resume a paused session. |
POST | /api/cases/:id/session/abort | Abort the active session. Lock is released. |