# Deacon Agent in Gas Town Health Monitoring: Architecture and Responsibilities > Discover the Deacon agent's role in Gas Town health monitoring discover its architecture and how it supervises system liveness and automated recovery. - Repository: [Gas Town Hall/gastown](https://github.com/gastownhall/gastown) - Tags: architecture - Published: 2026-07-07 --- **The Deacon acts as Gas Town's central health-supervisor daemon, maintaining system liveness through a persistent tmux session that executes patrol cycles, manages heartbeat state, and orchestrates automated recovery across the entire deployment.** The **Deacon** is the foundational monitoring component of the Gas Town ecosystem, implemented in the `gastownhall/gastown` open-source repository. As the primary watchdog process, it runs continuously as a tmux session named `hq-deacon`, forming the critical link between infrastructure health detection and automated remediation. Understanding the Deacon agent role in Gas Town health monitoring is essential for operators maintaining production deployments and debugging system-wide health issues. ## What Is the Deacon Agent? The Deacon operates as a background supervisor daemon that anchors the *watchdog chain* responsible for keeping the Gas Town system alive. According to [`docs/overview.md`](https://github.com/gastownhall/gastown/blob/main/docs/overview.md) (lines 31-32), the Deacon executes periodic patrol loops that scan town and rig directories for pending work, plugin gates, and health-check state files. It maintains its own liveness state in a JSON heartbeat file, allowing other agents like **Witness** and **Dogs** to detect stale or dead Deacon processes without network dependencies. ## Core Health Monitoring Responsibilities The Deacon fulfills several critical health monitoring duties that ensure ecosystem stability through continuous observation and intervention. ### Continuous Patrol Cycles Every daemon tick, the Deacon executes a **patrol** cycle that scans directories across the deployment. As documented in [`docs/design/polecat-lifecycle-patrol.md`](https://github.com/gastownhall/gastown/blob/main/docs/design/polecat-lifecycle-patrol.md) (lines 53-55), this patrol detects unserviced requests such as orphaned beads or stale witness sessions. When the Deacon identifies stalled work during a rig-wide patrol, it nudges the Witness agent to restart, ensuring continuous service availability without manual intervention. ### Heartbeat and State Tracking The Deacon maintains a JSON heartbeat file at `~/gt/deacon/heartbeat.json` that is updated each patrol iteration. According to [`docs/design/dog-infrastructure.md`](https://github.com/gastownhall/gastown/blob/main/docs/design/dog-infrastructure.md) (lines 25-27), this heartbeat serves as the canonical health indicator for the Deacon itself; other agents reference this file to determine if the Deacon is responsive, and a stale timestamp triggers failure detection protocols across the system. ### Manual and Automated Health Checks The Deacon supports explicit health validation through the `gt deacon health-check` command, implemented in [`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go). As noted in [`docs/design/dog-infrastructure.md`](https://github.com/gastownhall/gastown/blob/main/docs/design/dog-infrastructure.md) (lines 56-58), this command verifies the Deacon's own liveness and the health status of its managed Dogs. Additionally, the Deacon responds to `HEALTH_CHECK` nudges, executing its patrol logic on demand: ```bash # Trigger a manual health check gt deacon health-check # Send a health-check nudge to stimulate patrol gt nudge deacon "HEALTH_CHECK" ``` ## Dog Orchestration and Plugin Execution Beyond passive monitoring, the Deacon actively manages **Dog** agents—short-lived processes that perform infrastructure tasks such as Boot operations and log rotation. Dog state persists under `~/gt/deacon/dogs/…`, where the Deacon spawns, monitors, and retires these agents as needed. During patrol cycles, the Deacon also evaluates plugin gates in town and rig directories, executing enabled plugins asynchronously without blocking the main patrol loop. As described in [`docs/design/plugin-system.md`](https://github.com/gastownhall/gastown/blob/main/docs/design/plugin-system.md) (lines 9-14), this non-blocking execution ensures that plugin operations do not delay critical health monitoring tasks. ```bash # List active Dogs managed by the Deacon gt dog pool status # Observe Deacon patrol activity in daemon logs tail -f ~/gt/daemon/daemon.log ``` ## Escalation to the Mayor If automated recovery fails, the Deacon escalates unresolved issues to the **Mayor** for manual intervention. As defined in [`docs/design/polecat-lifecycle-patrol.md`](https://github.com/gastownhall/gastown/blob/main/docs/design/polecat-lifecycle-patrol.md) (lines 58-61), escalation policies in the Deacon's event matrix forward beads to the Mayor when the system encounters unresolvable states. This hierarchical approach ensures that persistent failures receive human attention while routine issues remain automated. ## Summary - The Deacon runs as a persistent tmux session (`hq-deacon`) and serves as the central supervisor in Gas Town's watchdog chain. - It maintains a JSON heartbeat at `~/gt/deacon/heartbeat.json` that other agents monitor for liveness detection, as documented in the Dog infrastructure specification. - Patrol cycles scan for stalled work and trigger recovery nudges to agents like the Witness when unserviced requests are detected. - The `gt deacon health-check` command and `HEALTH_CHECK` nudges provide manual and stimulated health verification interfaces. - The Deacon orchestrates Dog agents under `~/gt/deacon/dogs/…` and executes plugins asynchronously during patrol without blocking. - Unresolvable issues escalate to the Mayor through defined event matrix policies defined in the patrol lifecycle documentation. ## Frequently Asked Questions ### How does the Deacon communicate its health status to other agents? The Deacon writes a refreshed JSON heartbeat to `~/gt/deacon/heartbeat.json` during every patrol cycle. According to [`docs/design/dog-infrastructure.md`](https://github.com/gastownhall/gastown/blob/main/docs/design/dog-infrastructure.md) (lines 25-27), agents like the Witness and Dogs read this file to verify the Deacon is alive; if the timestamp becomes stale, they initiate failure detection protocols. This state-based approach eliminates the need for active network heartbeats. ### What happens when the Deacon detects a stalled Witness session? When the patrol cycle identifies unserviced requests or stale witness sessions, the Deacon nudges the Witness agent to restart. This detection and rescue mechanism, defined in [`docs/design/polecat-lifecycle-patrol.md`](https://github.com/gastownhall/gastown/blob/main/docs/design/polecat-lifecycle-patrol.md) (lines 53-55), ensures that temporary failures in the Witness do not result in permanently orphaned work or beads. ### Where does the Deacon store Dog agent state information? The Deacon maintains Dog agent state under `~/gt/deacon/dogs/…`, with each Dog's configuration and runtime data stored in dedicated subdirectories. As detailed in [`docs/design/dog-infrastructure.md`](https://github.com/gastownhall/gastown/blob/main/docs/design/dog-infrastructure.md) (lines 22-33), this file-based state management allows the Deacon to spawn short-lived infrastructure Dogs, monitor their execution, and clean up resources after completion. ### Can I manually trigger a health check without waiting for the patrol interval? Yes. Operators can trigger immediate health validation using `gt deacon health-check`, which is implemented in [`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go). Alternatively, sending a `HEALTH_CHECK` nudge via `gt nudge deacon "HEALTH_CHECK"` stimulates the Deacon to run its patrol cycle on demand, useful for debugging or verifying responsiveness during incidents.