Observability
Observability guide for the Coven daemon: health checks, daemon status, logs, socket checks, harness PATH checks, and diagnostic evidence for support.
2 min read
Useful daemon debugging starts with current evidence: process status, socket health, API compatibility, store reachability, and harness availability.
Fast check
Run:
coven daemon statusOn Unix-like hosts, confirm the socket route:
curl --unix-socket "$HOME/.coven/coven.sock" \
http://localhost/api/v1/healthIf you use a custom state directory, replace $HOME/.coven with $COVEN_HOME.
On Windows, use the owner-only named pipe reported by coven daemon status;
the curl example above is Unix-specific.
What to capture
| Evidence | Command or source | Why it matters |
|---|---|---|
| Daemon status | coven daemon status | Confirms pid, socket path, uptime, and API version. |
| Health response | GET /api/v1/health | Confirms the socket is reachable and the contract is compatible. |
| Capabilities | GET /api/v1/capabilities | Confirms the daemon sees expected features and adapters. |
| Session record | GET /api/v1/sessions/:id | Shows the daemon's status for one piece of work. |
| Events | GET /api/v1/events?sessionId=... | Shows output, input, status, and exit sequence for replay. |
| Harness path | which codex, which claude | Confirms the selected harness exists in the daemon environment. |
Do not paste secrets, provider tokens, private gateway URLs, or raw credentials into issues.
Logs
The daemon keeps an append-only recovery log at $COVEN_HOME/daemon-recovery.log. Each line is timestamped and records lifecycle and recovery evidence:
- Daemon startups (pid and socket path).
- Termination of unreachable duplicate daemons.
- Accept-loop and API handler errors.
- Panics, including a captured backtrace.
Read it first when the daemon restarted unexpectedly or a socket was left behind. The lock files daemon.lock (lifecycle orchestration) and daemon-serve.lock (single-writer serve guard) sit next to it; see Configuration and COVEN_HOME for the full state-directory layout.
Daemon logs should answer:
- Did the daemon bind the expected socket?
- Did the store open?
- Did the health route serve the expected contract?
- Did a launch request fail validation?
- Did a harness spawn fail?
- Did a live input or kill request target a non-live session?
When reading logs, search around the relevant session id, pid, timestamp, or structured error code.
Diagnostics bundle posture
Diagnostic output should redact secret-shaped values by default. Still review bundles before sharing them publicly, because session output can include private paths, prompts, and model responses.
Good issue reports include:
- Coven version.
- Operating system.
- Install path and package manager.
- Whether
COVEN_HOMEis customized. coven daemon statusoutput with secrets removed.- Health response with private paths redacted if necessary.
- The failing command and exact structured error code.
Common symptoms
| Symptom | First check |
|---|---|
| Connection refused | Is the daemon started? Is the socket path correct? |
| Unsupported API version | Are the client and daemon from compatible releases? |
| Harness not found | Does the daemon environment have the harness on PATH? |
| Session not live | Did the process exit, crash, get killed, or become orphaned? |
| cwd rejected | Does cwd canonicalize inside the submitted project root? |
Related
Last updated on