MCP SERVER
Cross-session awareness for parallel AI agents. Advisory locks, conflict detection, and lifecycle tracking — so 2–7 sessions don't step on each other.
| Tool | Purpose | Returns |
|---|---|---|
| peers | List all active peer sessions — repos, branches, files, intents, last activity. Auto-detects calling session via PID ancestry. Kills orphaned processes as a side effect. | Sessions grouped by status (active, dormant, recent). Counts per category. |
| check | Check if specific files, directories, or branches overlap with another session's claims or file touches. Path overlap uses prefix matching — claiming a directory covers all files beneath it. | Conflict list with peer details (intent, slug, activity age). Clear/conflict boolean. |
| announce | Update session state — intent, repo context, flow phase, file touches, or slug. Called automatically by the roost-sync plugin on every tool call. Each field is optional; only provided fields merge. | Updated session summary with touch count and claim count. |
| claim | Advisory soft locks on paths. Three actions: claim (add paths), release (remove specific paths), clear (release all). Claims warn peers but never block — coordination, not enforcement. | Current claims list. Warnings if paths overlap with peer claims. |
| close | End a session as completed (with result summary) or abandoned (with reason). Clears all claims. Preserves the session file for history. Guard prevents double-close. | Closed session record with status, result, timestamp, and touch count. |
| cleanup | Remove old terminal session files — dormant, completed, or abandoned. Defaults to dry-run preview. Configurable age threshold (default 7 days) and status filter. | Prune candidates with age and status. Dry-run preview or deletion count. |
Active — PID alive, activity within 30 minutes. Stale — PID alive, idle beyond 30 minutes. Both are visible to peers and hold their claims. The distinction lets other sessions gauge whether a conflict is with someone actively working or someone who walked away.
Completed — session closed with a result summary. Abandoned — session closed without finishing its intent. Both clear all claims on close. Session files are preserved for history and analytics — cleanup removes them after a configurable retention period.
The process died without calling close. Roost detects this via PID liveness checks — process.kill(pid, 0) returns false. Dormant sessions preserve their full state for resumption. When a new process starts with the same session ID, the session becomes active again.
The lifecycle is intentionally simple: announce → work → close. No registration step, no handshake. The roost-sync plugin handles heartbeats and file touch tracking automatically. Sessions that crash are detected by PID checks, not timeouts.
The cleanest path. If OPENCODE_SESSION_ID is set in the server's environment, use it directly. The roost-sync plugin injects this into shell environments so child processes inherit session identity.
The plugin writes a PID map on every scout_activate — mapping the OpenCode process PID to its session ID. The server reads this map and walks the process ancestry tree (up to 5 levels via ps -o ppid=) looking for a match.
Fallback when the PID map is empty (first tool call before the plugin writes it). Reads all session files and matches their stored PID against the server's process ancestry. Only considers non-terminal sessions.
All three strategies run in priority order on every tool call. The caller never needs to pass a session ID explicitly — it's always optional, always auto-detected. This is what makes roost invisible during normal work.
The roost-sync plugin is the primary data source. It hooks into OpenCode's tool call lifecycle: heartbeats on every call (keeps sessions active), tracks file touches from write/edit operations, and writes the PID map on scout_activate. Without the plugin, sessions still work but require manual announce calls and explicit session IDs.
Grounder reads session state for analytics — cost tracking, tool usage, and session duration all key off the session ID that roost manages. Flowbot writes flow state back through announce, making phase transitions visible to peers. The AGENTS.md instruction file tells all sessions to call peers at startup and close at shutdown.
The server that watches the watchers — and tells them to coordinate.