Status Command
Overview
The symphony status command provides real-time visibility into the orchestrator's operational state. It displays the orchestrator's process status (running/stopped), currently executing agents with PIDs and durations, pending work in the queue, and recent agent run history. This is the primary tool for monitoring orchestration activities and debugging agent execution issues.
How It Works
The status command follows this sequence:
Query Strategy
Running agents and queued issues are determined by explicit status checks:
- Running agents:
agent_runs.status = 'running' - Queued issues:
issues.status = 'todo'(sorted by priority ascending) - Recent runs:
agent_runs.status != 'running' AND != 'preparing', sorted by finishedAt descending, limited to 10
Each agent_run includes issueId which is joined to fetch the issue identifier and title for display.
Process Management
The orchestrator's process state is determined by reading .symphony/symphony.pid:
- File exists + process responding to signal 0 → running (blue badge)
- File missing or process dead → not running (plain text)
The PID check uses process.kill(pid, 0) (POSIX signal 0) to test liveness without terminating the process.
Key Components
| File | Responsibility |
|---|---|
cli/index.ts | Command router; handles 'status' entry point |
cli/commands/status.ts | Core command logic: queries and formatting functions |
cli/utils/initCli.ts | Database initialization (config, migrations) |
cli/utils/pid.ts | PID file read/write/check operations |
cli/utils/output.ts | Terminal formatting (tables, colors, durations) |
Design Decisions
1. PID-Based Process Status vs. Database Flag
Choice: Read .symphony/symphony.pid and use process.kill(pid, 0) to check liveness.
Rationale: PID file is the source of truth for orchestrator identity. Database flags could drift if the process crashes unexpectedly. Signal 0 is OS-level and reliable. Keeps status check fast and non-intrusive (no DB query needed).
2. SQL-First Targeted Queries
Choice: Use narrow projected SQL queries for each section, with a join for running agents, SQL ordering for queued issues, and SQL filtering/order/limit plus a batched issue lookup for recent runs.
Rationale: Each section still answers a distinct question, but the command avoids N+1 issue lookups and full-table scans of agent_runs. This keeps the CLI responsive as history grows while preserving the same output contract.
3. Recent Runs Limited to 10
Choice: Fixed limit of 10 most recent completed runs.
Rationale: Prevents terminal spam. Covers last 10-30 minutes of activity (depending on duration). Users can check the web dashboard or database for extended history. Keeps command output scannable at a glance.
4. Color-Coded Status Badges
Choice: ANSI color codes for status values (blue='running', green='succeeded', red='failed', yellow='review', gray='cancelled').
Rationale: Terminal users scan output quickly. Colors provide instant visual feedback. Consistent with other CLI tools (npm, cargo, etc.). Colors are optional; output degrades gracefully if unsupported.
5. Duration Formatting
Choice: Human-readable format (1h 5m 30s, 2m 15s, 45s) instead of seconds.
Rationale: Developers naturally estimate task duration in hours/minutes. Raw seconds require mental conversion. Duration can range from seconds to hours, so format adapts to magnitude.
Related Docs
- CLI Entry Point Architecture — Overview of CLI module structure and command routing
- Orchestrator Tick Loop — Details on orchestrator state management and agent_runs table
- Database Schema — agent_runs and issues table definitions
Known Gaps
- Orphaned processes: If orchestrator crashes without cleaning up PID file, status command will incorrectly show "running" for a dead process until the PID file is manually deleted.
- Multi-instance safety: No check prevents multiple orchestrator instances. Status shows only the one whose PID is in the file.
- Agent stdout/stderr: Command does not display agent output or logs. Users must check worktree files or web dashboard for detailed logs.