Session Lifecycle
How sessions start, run, and end.
Session Lifecycle
This document explains what happens from coven run through completion, replay, archive, summon, and deletion.
Lifecycle States
The current store records session status as a string.
| State | Category | Meaning |
|---|---|---|
created | Startup | The session record exists before live execution begins. |
running | Live | The harness process is active under daemon supervision. |
completed | Terminal | The harness exited successfully. |
failed | Terminal | Setup or launch failed before normal completion. |
killed | Terminal | The daemon accepted a live kill request and recorded a kill event. |
orphaned | Recovery | A previous daemon stopped while a session was still marked running. |
Archive state is stored separately as archived_at. A completed or failed session can be hidden from the active list without changing its final status.
The diagram above is normative for the v0 store. running sessions cannot be archived or sacrificed directly — kill them or wait for exit first. created → running is the only transition that requires PTY spawn; every other transition is a store-only state change managed by the Rust daemon. coven summon restores an archived session to whichever terminal status it held before archival (completed, failed, killed, or orphaned).
Launch Path
The normal launch flow keeps validation in the daemon.
| Step | Owner | Action |
|---|---|---|
| 1 | User or client | Sends a task through the CLI or local API. |
| 2 | Daemon | Resolves the project root. |
| 3 | Daemon | Canonicalizes the project root and working directory. |
| 4 | Daemon | Rejects outside-root working directories. |
| 5 | Daemon | Verifies the harness id is supported. |
| 6 | Store | Creates a session record in SQLite. |
| 7 | Daemon | Spawns the harness in a PTY using argv APIs. |
| 8 | Event log | Writes output and exit data as events. |
| 9 | Store | Updates session status and exit code. |
The Rust layer performs the authority checks even when a TypeScript client has already validated the request for UX.
Detached Records
coven run ... --detach creates the session record without launching the harness. This is useful for testing and development flows that need a ledger record without starting an external process.
Detached records should not be presented as completed agent work.
Attach and Replay
coven attach <session-id> replays known event output and follows live output when the session is still active.
For a completed session, attach acts like a log viewer. For a running session, attach also forwards input to the live daemon session.
Live Input And Kill
Live session control is available through the daemon API:
POST /api/v1/sessions/:id/inputwith{ "data": "..." }forwards input to a verifiedrunningsession and records aninputevent.POST /api/v1/sessions/:id/killstops a verifiedrunningsession, changes its status tokilled, and records akillevent.
Both endpoints return 202 { "ok": true, "accepted": true } on success. Unknown session ids return 404 session_not_found. Existing sessions that are completed, failed, killed, archived, or orphaned return 409 session_not_live; clients should show those records as replay/log surfaces instead of input targets.
Session Browser Behavior
coven sessions chooses output mode based on context.
| Mode | Trigger | Behavior |
|---|---|---|
| Interactive browser | Interactive terminal | Opens the session browser. |
| Plain table | Piped output or --plain | Prints table output for copy/paste and scripts. |
| JSON records | --json | Prints machine-readable session records for local clients. |
| Archived included | --all | Includes archived sessions. |
| Forced browser | --manage | Forces the browser. |
The browser offers contextual actions so users do not have to memorize session ids.
Archive
Archive hides a non-running session from the default active list while preserving the session record and event log.
coven archive <session-id>Use archive for old work that should remain inspectable.
Summon
Summon restores an archived session to the active list and then replays/follows it:
coven summon <session-id>Summon does not re-run the original harness prompt. It changes archive state and opens the existing record.
Sacrifice
Sacrifice permanently deletes a non-running session and cascades deletion to its events:
coven sacrifice <session-id> --yesThe command refuses live sessions. The interactive browser asks the user to type sacrifice before deletion.
Use sacrifice only when the session and its logs should be removed from the local ledger.
Orphan Recovery
If the daemon starts and finds sessions that were marked running from a previous daemon lifetime, those sessions are marked orphaned.
An orphaned session means Coven no longer owns a live process for that record. The event log may still be useful, but live input and kill operations should fail.
Event Durability
Events are append-only records in SQLite. This gives clients a stable replay source even when the original PTY process has exited.
Do not intentionally write secrets, environment dumps, private URLs, or token-bearing command output into events. Coven cannot guarantee that harness output is secret-free, so users should avoid running untrusted prompts in sensitive repositories.
Session Lifecycle
Last updated on