Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.opencoven.ai/llms.txt

Use this file to discover all available pages before exploring further.

Every Coven session moves through the same states, regardless of which harness is driving it.

​
State definitions

StateMeaning
pendingDaemon accepted the request; PTY not yet spawned.
runningPTY is live; output and input flow through Coven.
completedHarness exited with code 0.
failedHarness exited with a non-zero code. The exit code is recorded.
killedOperator or client called kill.
archivedSession is hidden from the active list. Events preserved.

​
Launch

coven run codex "describe this repo"
Equivalent socket call: 
POST /api/v1/sessions
Content-Type: application/json

{
  "projectRoot": "/absolute/path",
  "cwd": "/absolute/path/subdir",
  "harness": "codex",
  "prompt": "describe this repo"
}
The Rust daemon revalidates projectRoot and cwd before spawning the PTY. See Authority boundary.

​
Attach

coven attach <session-id>
attach streams output from the event log (replay) and then follows live output. Input is forwarded to the PTY. Use Ctrl-] to detach without killing the session.

​
Archive / summon / sacrifice

These are the three rituals around finished sessions:

Archive

Hide a non-running session. Reversible. Events preserved.

Summon

Restore an archived session to the active list, then replay/follow it.

Sacrifice

Permanently delete. Refuses live sessions. Requires --yes.

​
Orphan recovery

If the daemon restarts while a PTY is running, the session is marked orphaned. On the next start, the daemon:
  1. Reads the session ledger.
  2. Marks orphaned sessions as failed with a recovery note in their event stream.
  3. Refuses to re-attach to a dead PTY.
See Orphan recovery.