Sessions

Coven records project-scoped harness work as sessions. Use coven sessions to browse recent work and choose session actions without copying ids.

coven sessions

The daemon owns session state; see Daemon lifecycle for recovery and restart behavior.

Rituals Cheat Sheet

Coven names its session-management verbs rituals. The whimsy is deliberate; the semantics are conventional and conservative. This table is the full mapping in one place:

Ritual	Plain meaning	Command	Allowed for	Reversible	Events
Archive	Hide from the active list	`coven archive <session-id>`	Any non-running session	Yes — summon it back	Preserved
Summon	Restore an archived record	`coven summon <session-id>`	Archived sessions	Yes — archive again	Preserved
Sacrifice	Delete permanently	`coven sacrifice <session-id> --yes`	Any non-running session	No	Deleted

Three rules cover almost every question:

Running sessions are untouchable. Kill the process or wait for exit before any ritual applies.
Only sacrifice destroys data. Archive and summon flip visibility; the session record and event log survive both.
Summon does not re-run anything. It restores the record to its prior terminal status (completed, failed, killed, or orphaned) and opens the existing log.

Rituals are CLI-owned in coven.daemon.v1: the public socket API has no archive, summon, or sacrifice endpoints yet, and GET /api/v1/sessions simply excludes archived records. Clients that need record management should use the CLI verbs above.

The rituals in detail:

Listing modes

Command	Output
`coven sessions`	Interactive browser in a terminal; table output when piped.
`coven sessions --all`	Includes archived sessions.
`coven sessions --manage`	Forces the interactive session browser.
`coven sessions --plain`	Forces a plain table for scripts and copying.
`coven sessions --json`	Prints a JSON `sessions` array for local clients and scripts.

Use --json for integrations and --plain for shell scripts or support snippets.

The plain table widens each column to fit its longest value, prints control characters in titles as escapes such as \u{a}, and cuts titles longer than 48 characters with …. Use --json when you need the complete title.

Search and inspect

Search recorded event payloads with FTS5 query syntax:

coven sessions search "auth OR jwt"

Inspect one session without attaching:

coven sessions show <session-id>
coven sessions events <session-id> --limit 100
coven sessions log <session-id>

show prints the session record and ritual state. events prints redacted event payloads and accepts --after-seq plus --limit. log renders the recorded log lines. Each command also supports --json.

Session references may be full ids or unique prefixes. Ambiguous prefixes fail instead of selecting an arbitrary session.

Attach

Replay and follow a session:

coven attach <session-id>

For live daemon sessions, attach can also forward input to the running harness.

Kill

Stop a running session's harness process while keeping its event log:

coven kill <session-id>

Use a full session id or a unique prefix. The command requires a running session and sends the kill request to the daemon, which owns the process. It does not archive or delete the session. After it stops, use coven archive <session-id> when you want to hide the retained record.

kill currently works on Unix-like systems. If the store says a session is running but the daemon has no live process, the command reports stale state instead of claiming success. Inspect coven daemon status and coven sessions, then follow Recovery and upgrades.

Summon

Restore an archived session, then attach:

coven summon <session-id>

Use coven sessions --all when you need to find archived session ids.

Sacrifice

Permanently delete a non-running session and its event log:

coven sacrifice <session-id> --yes

Sacrifice is destructive. It requires --yes and refuses running sessions.

Run for creating sessions.
Daemon lifecycle for live-session daemon behavior.
Recovery and upgrades for stale local IPC and orphaned sessions.

On this page