Project Roots
How Coven resolves project roots for harness sessions and why launch requests cannot widen the project boundary.
1 min read
Every harness session starts from a project root. Coven resolves and canonicalizes that root before it launches a PTY or records the session.
Why it matters
Project roots make sessions auditable. A session record can answer:
- Which repository or project was the work tied to?
- Which harness id ran?
- Which working directory did the process start in?
- Which event log belongs to that run?
Without a project root, a harness run is just a loose process. Coven's job is to make it a named, reviewable session.
CLI behavior
Run from inside a project:
cd /path/to/project
coven run codex "fix the failing tests"If Coven cannot resolve a project root, coven doctor and coven run give setup evidence instead of launching a vague process.
Client behavior
Clients should treat project root as authority-sensitive input. They can collect and display it, but the daemon still validates it.
On every launch request the daemon canonicalizes the supplied projectRoot (resolving symlinks and relative segments) and then requires the working directory to canonicalize to the root itself or a path inside it. A projectRoot that does not exist fails resolution, and a cwd that escapes the canonical root — including via symlink — is rejected before any PTY is spawned.
Do not trust a browser or chat client to enforce project boundaries on its own. The daemon remains the validation boundary described in Daemon security posture.
Related
Last updated on