Monitor Dashboard Reference

Monitor Dashboard Reference

The monitor process serves a React SPA dashboard at http://localhost:9106 (the default monitor port). This page is a complete reference for the dashboard’s tabs, pipeline states, block reasons, column metrics, and operator controls.

For the interactive REST API that backs the dashboard, see api.md.

---

Access

Navigate to http://localhost:9106 in a browser. In Docker Compose deployments the port mapping is 9106:9106 on the monitor container; in bare-metal deployments the monitor binds to its configured health_port (default 9106).

---

Authentication

When agents.monitor.auth is configured in colony.config.yaml, all dashboard and API endpoints require a valid session. The dashboard renders an in-page login form — no native browser Basic Auth prompt is shown.

agents:
  monitor:
    auth:
      username: colony
      password_env: COLONY_DASHBOARD_PASSWORD

Login flow:

1. The dashboard login form POST /api/auth/login with your username and password.
2. On success, the monitor sets a signed COLONY_SESSION httpOnly cookie valid for 12 hours.
3. After 12 hours, or after any monitor process restart, the cookie is invalidated and you must log in again.

Note: The session signing secret is generated fresh on each monitor restart. A monitor redeploy logs out all active sessions.

When no auth block is configured, the dashboard is open to all visitors with network access.

For programmatic and CLI access, see api.md — Authentication.

---

Header & Global Controls

Every page of the dashboard renders a persistent header row above the tab bar and a three-card status strip below it. The controls documented here are always visible regardless of which tab is active.

Jump to Issue

A text input in the top-right corner of the header accepts an issue reference and opens the issue-detail panel when Enter is pressed.

Format	Example	Behaviour
#N	#42	Opens issue 42 in the first configured repo.
owner/repo#N	acme/api#42	Opens issue 42 in the specified repo.

An inline error is shown if the reference cannot be parsed or no repos are available.

RefreshBar

Displays the timestamp of the last successful data fetch alongside a ↻ button that triggers an immediate reload.

Connection Status

A badge next to the RefreshBar reflects the real-time connection state:

Badge	Meaning
Live	Dashboard is receiving real-time push updates via SSE.
Polling	SSE connection is not active; dashboard falls back to 30-second interval polling.

Status-Bar Cards

Three cards appear below the header row.

Card	Description
Status	Overall pipeline health reported by the monitor: healthy, degraded, or unhealthy.
Uptime	How long the monitor process has been running since its last restart, formatted as Xh Ym.
Cost: <window>	Total LLM API spend in the selected time window. Click to cycle through 24h → 7d → 30d → Lifetime. The active window label is shown in the card header; hover for a tooltip description.

Help and Log Out

Two buttons sit in the top-right corner of the header:

Button	Effect
?	Opens the tab-contextual Help & Glossary panel, automatically scrolling to the section relevant to the current tab. A second ? button appears inline at the right end of the tab bar and opens the same panel.
Log out	Ends the active session and returns to the login form. Relevant only when agents.monitor.auth is configured.

Multi-Repo CTA Banner

When more than one repository is detected in the pipeline, a banner appears below the header row:

Running multi-repo mode. Colony Cloud provides full multi-repo management — runcolony.com

The banner is not shown in single-repo deployments.

---

Tab Catalog

The dashboard is organized into tabs. Click a tab name to navigate to it. Hover the tab label for a tooltip with its description (populated from TAB_GLOSSARY in packages/dashboard/src/glossary.ts).

Tab	Description
Pipeline	Overview of worker pool health, in-flight tasks, and per-repo state distribution.
Activity	Chronological feed of recent issue state transitions across all repos.
Cost	Breakdown of LLM API spending by issue, repo, and time window.
Tracks	Manage issue tracks — persistent groups of related issues that share a theme or goal.
Write Queue	Pending VCS projection writes (GitHub label syncs) queued in the outbox drainer.
Blocked	Issues in the failure-blocked state, with error patterns and operator unblock actions.
Dead Letters	Tasks that failed permanently and were moved to the dead-letter queue.
Consistency	Data-consistency findings from periodic audits — stale flags, orphan issues, subtask edge drift, SI linkage gaps, and label/Postgres mismatches — with per-finding one-click repair actions.
Queue	Live view of the work_tasks Postgres queue: pending, claimed, and recently completed tasks.
Regression	Regression guard results — automated checks that protect the pipeline from entering broken states.
Events	Raw event log of webhook deliveries, state transitions, and agent actions.
Logs	Structured log output from the monitor process (Pino JSON lines).
System	Runtime health: Node.js version, memory usage, Postgres connectivity, and uptime.
Workflows	Registered workflow definitions and their state machine graphs.
Workers	Per-worker status: current task, lease age, drain state, and manual controls.
API	Interactive OpenAPI reference for the monitor REST API.
Strategy	Strategist proposal review and snapshot approval — view and approve AI-generated strategy proposals. Decline a proposal by updating the Charter.
Charter	Edit the strategy charter — define goals and constraints that guide the Strategist when generating proposals.
Review Queue	Every open pull request awaiting human review, grouped by status. Ready-for-review items (human action required) are listed first, visually distinct from auto-merging and in-progress PRs.

---

Pipeline State Reference

Pipeline states are displayed as labels on GitHub issues and throughout the dashboard. Definitions are sourced from PIPELINE_STATE_GLOSSARY in packages/dashboard/src/glossary.ts.

State	Label	Description
unlabeled	Unlabeled	Issue exists in GitHub but has not been picked up by Colony yet.
new	New	Issue has been enqueued and is awaiting analysis.
planning	Planning	Epic is being decomposed into subtasks by the planner.
analyzing	Analyzing	Issue is being analyzed to produce an implementation plan.
needs-clarification	Needs Clarification	Analyzer could not determine intent; waiting for the author to clarify.
ready-for-dev	Ready for Dev	Analysis complete; issue is queued for implementation.
dependency-blocked	Dependency Blocked	Issue is waiting for one or more upstream issues to complete.
failure-blocked	Failure Blocked	Issue hit a hard block (repeated failures, cost cap, etc.) and needs operator action.
changes-requested	Changes Requested	PR reviewer requested changes; developer will revise and resubmit.
in-review	In Review	Pull request is open and undergoing automated or human review.
merge-pending	Merge Pending	PR has passed review and is queued for merge.
human-review-ready	Human Review Ready	Automated checks passed; PR is ready for a human reviewer.
waiting-for-subtasks	Waiting for Subtasks	Epic is waiting for all child subtasks to reach Done before it can proceed.
done	Done	Issue is complete; pull request has been merged.
paused	Paused	Issue processing is suspended by an operator; resumes when unpaused.

---

Block Reason Reference

When an issue reaches failure-blocked, a block_reason code is recorded. These codes are shown in the Blocked tab and in the Help & Glossary panel. Definitions are sourced from BLOCK_REASON_GLOSSARY in packages/dashboard/src/glossary.ts.

Code	Label	Description
failure	Max Retries	Issue exceeded the maximum retry count after repeated generic failures.
build_failure	Build Failure	The build or compile step failed and could not be automatically fixed.
ci_hard_failure	CI Hard Failure	A CI check failed in a non-transient way (e.g., a required status check) and will not auto-retry.
cost_cap	Cost Cap	The per-issue or monthly cost cap was reached; increase or reset the limit to continue.
custom	Custom Block	Issue was routed to an operator decision — for example, a pull request was closed by a human without merging.
dependency	Dependency	Issue is blocked because a dependency issue has not completed yet.
empty_against_base	Empty Against Base	The PR diff against the target branch is empty; no effective changes were produced.
merge_conflict	Merge Conflict	The PR has a merge conflict; requires human or LLM resolution (non-transient, not auto-retried).
overlap	File Overlap	Another in-flight issue is modifying the same files; blocked to avoid conflicts.
reimplement_loop	Reimplement Loop	Developer has been sent back for re-implementation too many times without making progress.
review_crash	Review Crash	The reviewer agent crashed or timed out and could not be recovered.
review_cycle_limit	Review Cycle Limit	PR has gone through too many review-revise cycles without being approved.
conflict_rejection	Conflict Rejection	Changes were rejected due to conflicts introduced by a concurrently merged PR.
identical_failure	Identical Failure	The same error recurred without any change in output, indicating a stuck retry loop.
planning_failure	Planning Failure	Epic decomposition failed; the planner could not produce valid subtasks.
worktree_failure	Worktree Failure	Setting up the git worktree for this issue failed (e.g., disk space, submodule conflict).
unknown_reason	Unknown Reason	Block reason was not recorded; inspect the issue timeline for details.
dependency_cycle	Dependency Cycle	A circular dependency among issues was detected; manual resolution is required to break the cycle.

---

Needs Attention Panel

The Pipeline tab renders a warning-bordered Needs Attention (N) panel whenever Colony detects issues that require operator action. Each row shows the issue number, title, current state, a reason badge, how long the issue has been in that state, and inline action controls (pause/resume/unblock/retry/change state/cancel via the same IssueActions controls available in the issue detail panel).

Hovering a reason badge shows a tooltip with its description. The same descriptions appear in the Help & Glossary panel under Needs Attention Reasons.

Code	Badge Label	Description
human-review-ready	Review Ready	PR is awaiting human review approval; automated checks passed and no further agent action is needed.
blocked	Blocked	Issue hit a hard block and is in the failure-blocked state; operator must unblock, retry, or cancel.
needs-clarification	Needs Clarification	Analyzer could not determine intent; issue author must clarify the request before work can resume.
stale	Stale	Issue has been in its current state without progress for longer than the configured stale threshold.
needs-human	Needs Human	Issue requires direct operator intervention; Colony cannot proceed without human input.
token-expiry	Token Expired	A GitHub token used by this repository is expired or invalid; rotate the token to resume processing.
lingering-branch	Lingering Branch	A development branch for a completed issue was never deleted; clean it up or close the associated PR.

Definitions are sourced from NEEDS_ATTENTION_GLOSSARY in packages/dashboard/src/glossary.ts.

---

Review Queue Reference

The Review Queue tab groups open pull requests by their current status. Status badges are sourced from REVIEW_QUEUE_GLOSSARY in packages/dashboard/src/glossary.ts.

Status	Description
Ready For Review	PR has passed automated checks and is waiting for a human reviewer to approve or request changes.
Auto Merging	All approvals are in place; the merge is proceeding automatically with no human action needed.
Changes Requested	A reviewer has requested changes; the agent is addressing the feedback before re-requesting review.
Blocked	The PR is blocked and cannot proceed; operator intervention is required to unblock or cancel.
In Progress	Review is still in progress — automated checks or an LLM review are running.

---

Column and Metric Reference

Column headers in the dashboard tables expose tooltips explaining each metric. Full definitions are sourced from COLUMN_GLOSSARY in packages/dashboard/src/glossary.ts.

Column / Metric	Description
Heartbeat	Heartbeat freshness: fresh = last ping <90 s ago; stale = 90–300 s; dead = >300 s or never received. A dead worker may have crashed or lost its Postgres connection.
Status	Worker lifecycle state: idle = waiting for tasks; working = processing a task; draining = finishing the current task then stopping; stopped = shut down.
Pinned Issue	Issue and task type currently held by this worker’s lease. Use Force reclaim to release a stuck lease and return the task to the queue.
Task Status	Task lifecycle: pending = waiting in the queue for a free worker; claimed = a worker has acquired the lease and is actively processing this task.
Avg Wait	Average time tasks spend in the pending state before being claimed by a worker. High values indicate workers are saturated or the pool is undersized.
Oldest Pending	Age of the oldest task still waiting to be claimed. Highlighted when >5 minutes — a sign of queue backpressure or a stuck worker.
Cost Window	Click to cycle the cost display window: 24h / 7d / 30d = rolling window; Lifetime = all recorded history.
Projection Status	VCS write status: pending = queued to be sent to GitHub; failed = all retry attempts exhausted. Items remain here until retried or discarded.
Burn Rate	Estimated daily LLM API spending based on recent cost events, used to project when the monthly budget will be exhausted.
Projected Exhaustion	Estimated date when the monthly budget will be consumed at the current burn rate. Highlighted in orange when exhaustion falls within the current month.
Issue	Issue number and title identifying the pipeline item in this row.
Repo	The GitHub repository (owner/name) this item belongs to.
Agent	The agent or task type (e.g. analyze, develop, review) that performed the logged action.
Time	Timestamp of the event, transition, or error — displayed as relative time; hover for the exact local date and time.
Actions	Operator controls available for this row (pause, retry, unblock, cancel, etc.).
Error	The most recent error output from the agent run for this item.
Blocked Duration	How long the issue has been in its blocked state, calculated from the time it was first marked blocked.
Recommendation	Suggested operator action to resolve the block, generated by the pipeline monitor’s block-classification logic.
Reason	Why this issue requires human attention — one of: blocked, review-ready, needs-clarification, stale, needs-human, token-expiry, or lingering-branch.
Time in State	How long the issue has been in its current state without a pipeline transition.
From State	The pipeline state the issue was in when the failed transition was attempted.
Target State	The pipeline state the transition was trying to reach when it failed permanently.
Created	When this dead-letter entry was recorded — i.e. when the transition permanently failed.
Type	Category of the pipeline event (e.g. state_transition, claude_execution, error, self_healing). Click a row to expand the full event payload.
Summary	Human-readable digest of the event payload — varies by type (e.g. “new → analyzing” for state transitions, cost and duration for executions).
Transition	The state change that occurred, displayed as “From State → To State”.
Cost	LLM API cost in USD recorded for the agent run associated with this state transition.
KPI	The pipeline health metric being measured (e.g. block rate, mean cost per issue, review pass rate).
Current	The metric’s most recently computed value in the current measurement window.
Baseline	The reference value for this metric captured at the time the baseline snapshot was taken.
Delta	Percentage change from baseline to current value — positive means the metric increased.
Magnitude	Severity tier of the observed change (e.g. negligible, minor, moderate, major).
Direction	Whether the metric moved up or down from baseline — interpretation depends on the KPI (e.g. a higher block rate is bad; a higher review pass rate is good).
Status	Whether the metric has crossed the regression threshold — shown as a “regressed” badge when the KPI has degraded beyond the configured tolerance.
Trend	Sparkline chart showing the metric’s value across recent successive snapshots, oldest left to newest right.
Name	Unique identifier for the self-improvement track; used in API paths and log messages.
Label	GitHub label assigned to issues created under this track so they can be filtered and grouped.
Enabled	Whether the track is active — disabled tracks do not generate new issues during the cooldown evaluation cycle.
Cooldown	Minimum time in minutes that must elapse between consecutive issues created by this track.
Active Version	Current active prompt version for this track; increment by editing the prompt in the expanded row.
State	Internal state identifier (slug) as defined in the workflow YAML (e.g. analyzing, in-review).
Label	Human-readable display name for this workflow state shown in the dashboard.
Type	Behavioral trait of this state — active (executing), blocked, awaiting-human, or terminal (no outgoing transitions).
Executor	The executor plugin or built-in handler invoked when an issue enters this state (e.g. builtin:review, plugin:colony-content/analyze).
Transitions	List of valid next states reachable from this state according to the workflow graph.
Slug	Full GitHub identifier for the repository in owner/name format.
Branch	Default branch Colony targets when creating worktrees and opening pull requests for this repo.
Pool Size	Number of parallel workers configured to process tasks for this repository.
Setup Command	Shell command run after creating a git worktree for this repo (e.g. bundle install for Rails). Empty means the default npm install is used.
Agent	Name of the agent process (e.g. sprint-master, monitor, webhook-receiver) being reported on.
Status	Reported health of the agent — healthy (running and passing checks), unhealthy (failing but still up), or unknown.
Uptime	How long the agent process has been running since its last restart.
Consecutive Failures	Number of successive health-check cycles the agent has failed without recovering.
Last Error	Most recent error message captured from the agent’s health-check output.
Config Reload	Status of the last config reload applied to this agent — applied (changes took effect), rejected (validation failed), or none.
Kind	Category of the data-consistency finding: stale_blocked, stale_subtask_edge, orphan_missing_from_pg, si_linkage_gap, or label_drift.
Detail	Kind-specific audit detail — expand to view the raw fields that describe why this finding was raised.

---

Operator Controls

The dashboard exposes several controls for managing pipeline state. All controls call the monitor REST API; see api.md for the underlying endpoint details.

Workers Tab — Force Reclaim

The Workers tab shows a table of registered workers per repo. Each worker row displays a Force reclaim button only when that worker currently holds a pinned task (both a task type and issue number are recorded on the worker’s lease).

Control	Condition	Effect
Force reclaim	Worker has a pinned task	Releases the worker’s task lease and returns the task to the work_tasks queue so another worker can claim it. Use when a worker appears stuck but has not self-recovered.

Issues — Pause, Resume, Unblock, Retry, Change State, Cancel

Issue-level controls appear in the issue detail panel (accessed by clicking an issue number anywhere in the dashboard). Available controls depend on the issue’s current state and flags:

Control	Shown when	Effect
Pause	Issue is not paused and not done	Suspends issue processing. Adds the colony:paused label.
Resume	Issue is paused	Re-activates a paused issue and re-enqueues the work task.
Unblock	isBlocked is true	Opens a confirm dialog: “Are you sure you want to unblock #N? This will resume processing.” On confirm, removes colony:blocked and re-enqueues the work task.
Retry	State is one of: analyzing, in-review, merge-pending, planning	Re-enqueues the work task for the current state without changing the state.
Change State	Not done, not paused, and the workflow snapshot has valid outgoing transitions	Dropdown populated from GET …/valid-transitions. Selecting a target immediately forces the issue to that state via the workflow snapshot’s transition graph.
Cancel	Issue is not done	Opens a confirm dialog: “Are you sure you want to cancel #N? This will close the issue.” On confirm, transitions the issue to done.

Retry scope: Retry is only available for issues actively being processed (analyzing, in-review, merge-pending, planning). It is not shown for blocked, paused, or terminal issues.

Dead Letters Tab — Retry, Resolve, Resolve All

The Dead Letters tab lists state transitions that failed permanently and were moved to the dead-letter queue. Each row has two per-item actions, and a global action is available at the top of the table:

Control	Scope	Effect
Retry	Per dead-letter entry	Re-attempts the failed transition (POST /api/dead-letters/{id}/retry).
Resolve	Per dead-letter entry	Acknowledges and removes the dead letter without retrying (POST /api/dead-letters/{id}/resolve).
Resolve All (N)	All dead letters	Resolves every dead letter in the queue at once (POST /api/dead-letters/resolve-all). The count of entries is shown in the button label.

Consistency Tab — Per-finding Repairs

The Consistency tab lists data-consistency findings raised by periodic audits. Each finding row shows the affected issue, repository, kind badge, and an expandable detail field. For findings that have a repair action, a button appears in the Actions column; findings of kind label_drift self-heal automatically and show no button.

Control	Finding kind	Endpoint	Effect
Clear stale flag	stale_blocked	POST /api/consistency/:id/clear-flag	Clears the stale-blocked flag on the issue so the pipeline can re-evaluate it.
Resolve subtask edges	stale_subtask_edge	POST /api/consistency/:id/resolve-subtask-edges	Repairs stale parent/child subtask dependency edges in the pipeline store.
Enqueue orphan	orphan_missing_from_pg	POST /api/consistency/:id/enqueue-orphan	Re-enqueues an issue that exists on GitHub but is missing from the Postgres pipeline store.
Link SI issue	si_linkage_gap	POST /api/consistency/:id/link-si	Re-establishes the self-improvement issue ↔ track linkage in si_issues.

Note: label_drift findings (GitHub label out of sync with Postgres state) have no manual repair button — they are resolved automatically by the self-healing reconciler and will clear on the next audit cycle.

Write Queue Tab — Retry, Discard

The Write Queue (Projections) tab shows VCS write operations (GitHub label syncs) queued in the outbox drainer. Retry and Discard controls appear only for projections with status failed — pending projections are still in-flight and cannot be manually acted on.

Control	Condition	Effect
Retry	Projection status is failed	Resets the projection to pending for re-execution (POST /api/projections/{id}/retry).
Discard	Projection status is failed	Marks the projection as discarded, preventing further retries (POST /api/projections/{id}/discard).

Strategy Tab — Approve Strategy

The Strategy tab lists strategy snapshots for a repository. The detail panel on the right shows the selected snapshot’s intent, rationale, and portfolio changes. An Approve Strategy button appears only when the selected snapshot has status proposed. There is no Reject button — to decline a proposal, use the Charter tab to update the charter goals and wait for the Strategist to generate a new proposal.

Control	Condition	Effect
Approve Strategy	Snapshot status is proposed	Marks the snapshot as the active strategy (POST /api/strategy/{owner}/{repo}/snapshots/{version}/approve). The Strategist will start acting on the approved portfolio.

Charter Tab — Save Charter

The Charter tab provides a form for editing the strategy charter — the goals and risk envelope that guide the Strategist when generating proposals. Saving creates a new charter version and activates the Strategist.

Field	Type	Description
Goals	Textarea (required)	Free-text strategic goals for the repository.
Max auto size	Dropdown (small / medium / large / epic)	Largest issue size the Strategist may enqueue without operator approval.
Prefer	Textarea (one item per line)	Work types or attributes the Strategist should favour (e.g. small bugs, test coverage).
Avoid	Textarea (one item per line)	Work types or attributes the Strategist should avoid (e.g. breaking changes, large refactors).
Escalate when	Textarea (one item per line)	Conditions that should trigger operator review (e.g. cost per issue exceeds $5, block rate above 20%).

Click Save Charter to write the charter (PUT /api/strategy/{owner}/{repo}/charter). The version badge updates on success.

---

Built-in Help & Glossary Panel

The dashboard includes a built-in Dashboard Help & Glossary modal accessible from the top navigation bar. The panel contains six sections:

• Pipeline States — all states from PIPELINE_STATE_GLOSSARY
• Block Reasons — all reasons from BLOCK_REASON_GLOSSARY
• Dashboard Tabs — all tabs from TAB_GLOSSARY
• Columns & Metrics — all metrics from COLUMN_GLOSSARY
• Needs Attention Reasons — all reason codes from NEEDS_ATTENTION_GLOSSARY
• Review Queue — all statuses from REVIEW_QUEUE_GLOSSARY

The panel is tab-contextual: opening it via the ? button in the top navigation bar automatically scrolls to the section most relevant to the tab you are currently viewing. For example, opening help from the Review Queue tab scrolls directly to the Review Queue section; opening it from the Blocked tab scrolls to Block Reasons.

The panel content is identical to the reference tables in this document and is always in sync with the running dashboard version.