Gas Town Daemon Architecture¶

Type: Infrastructure architecture
Related: steve-yegge-gas-town, steve-yegge-gupp, steve-yegge-hierarchy, kelly-gas-town-gap-analysis, kelly-deacon-architecture

Overview¶

Gas Town's agent hierarchy (Mayor → Crew → Polecats) defines who does the work. The daemon architecture defines how the work stays healthy. Four long-lived Go processes — Deacon, Boot, Witness, and Refinery — form the infrastructure substrate that enforces GUPP, detects failures, audits quality, and routes work. Without them, Gas Town's agents would stall, drift, and decay silently.

These daemons are not agents. They don't use LLMs. They are deterministic Go binaries with fixed logic, predictable behavior, and no creative latitude. This is deliberate: the infrastructure layer must be reliable in ways that stochastic agents cannot be.

The Four Daemons¶

Deacon — The Patrol Daemon¶

Role: Liveness enforcement and stale-work detection
Runs: Continuous patrol loop
Config: ai.openclaw.deacon launchd agent (macOS) or systemd unit (Linux)

The Deacon is Gas Town's most critical daemon. It patrols all hooks in the system — every agent's work queue — and enforces GUPP at the infrastructure level. If a hook has been non-empty for longer than a configured timeout, the Deacon intervenes.

Responsibilities:
- Bead timeout detection — patrol all hooks, detect stale beads (work items that haven't been claimed or progressed within timeout)
- Stale agent detection — identify worker corpses (agents whose hooks show pending work but which have stopped processing)
- Auto-respawn — kill stuck agents, re-queue their beads for other agents to claim
- Completion hooks — fire subagent-complete notifications when a bead transitions to done (PIP-73)

The Deacon is the operationalization of steve-yegge-gupp: GUPP says "always run when work exists," and the Deacon ensures that "always" actually means always.

Failure mode without Deacon: Worker corpses accumulate. Hooks show pending work. No agent processes it. The pipeline silently stalls.

See kelly-deacon-architecture for the unified Deacon implementation (PIP-73).

Boot — The Triage Daemon¶

Role: Heartbeat handling and ephemeral task triage
Runs: Event-driven (on heartbeat signals)

Boot is a lightweight daemon that handles heartbeat traffic so the Deacon isn't interrupted by routine liveness pings. It also serves as an ephemeral triage agent — handling small, immediate tasks that don't warrant spawning a full polecat.

Responsibilities:
- Heartbeat offload — process routine liveness signals from all agents without burdening the Deacon's patrol loop
- Ephemeral triage — handle small tasks (status checks, simple lookups, metadata updates) that complete in seconds
- Signal routing — forward non-routine signals (errors, escalations) to the appropriate daemon or agent

Design rationale: As agent count scales (20–30 concurrent polecats), heartbeat traffic becomes significant. If the Deacon handles both patrol and heartbeat, patrol frequency degrades under load. Boot isolates these concerns.

Failure mode without Boot: Deacon patrol loop slows as heartbeat volume increases. Stale-work detection latency increases. Under heavy load, the Deacon may miss timeout windows.

Witness — The Quality Auditor¶

Role: Continuous quality monitoring across all active workers
Runs: Continuous audit loop
Scope: All active polecat and crew output

Witness is Gas Town's dedicated quality daemon. Unlike Kelly's TEA audit (a stage gate before release), Witness runs continuously — watching all workers as they produce output, catching quality issues in real time rather than at the end.

Responsibilities:
- Fuzzing — inject unexpected inputs or edge cases into agent workflows to test robustness
- Invariant checks — verify that agent output conforms to structural invariants (correct format, required fields, no forbidden patterns)
- Drift detection — identify when agent output gradually deviates from project standards (style drift, assumption drift, architectural drift)
- Heresy stamping — detect and flag "heresies" (wrong assumptions about system architecture that propagate through agent-generated code)

Witness vs TEA audit:
| Aspect | Witness | TEA Audit |
|--------|---------|-----------|
| Timing | Continuous, during work | Stage gate, before release |
| Scope | All active workers | Single deliverable |
| Depth | Lightweight checks | Three-phase deep audit |
| Output | Real-time alerts | Structured tea-summary.md |
| Skippable | No (daemon, not agent) | Tempting under deadline pressure |

Failure mode without Witness: Quality issues accumulate silently. Heresies propagate through multiple agents. By the time TEA catches them at release, fixing is expensive.

Refinery — The Routing Daemon¶

Role: Work decomposition, scheduling, and agent selection
Runs: On-demand (when new work enters the system)

Refinery is the daemon that converts high-level intent into executable work items. When the Mayor receives a vague epic from the human, Refinery decomposes it into a well-specified bead sequence that polecats can execute.

Responsibilities:
- Intent decomposition — break vague epics into atomic, well-specified beads
- Scheduling — determine execution order based on dependencies, priority, and resource availability
- Agent selection — match beads to the most appropriate available agent (polecat or crew)
- Retry management — handle failed beads by re-queuing with adjusted parameters or escalating

Refinery vs Kelly Router:
| Aspect | Refinery | Kelly Router |
|--------|----------|-------------|
| Granularity | Bead-level (small work items) | Task-level (larger units) |
| Method | Decompose epics → bead sequences | Route tasks → named leads |
| Infrastructure | Dedicated daemon | Main agent session |
| Scope | All work in the system | Pipeline orchestration |

Failure mode without Refinery: Work decomposition happens ad-hoc in agent sessions. Inconsistent granularity. Some beads are too large (agents choke), some too small (overhead dominates). No centralized scheduling awareness.

Daemon Lifecycle¶

All four daemons follow the same lifecycle model:

[Configured] → [Started] → [Running] → [Stopped/Killed]
                      ↑                       |
                      └───── [Restarted] ──────┘

Startup¶

• Daemons start at system boot (launchd on macOS, systemd on Linux)
• Each daemon reads its configuration from a shared config file
• Daemons register themselves with a shared service registry
• Startup order: Refinery → Boot → Deacon → Witness (Refinery must be ready before Deacon starts patrolling)

Runtime¶

• Daemons communicate via the Bead substrate (shared Dolt database)
• No direct daemon-to-daemon RPC — all coordination through Beads
• Each daemon maintains its own patrol/audit loop with configurable intervals
• Health checks: each daemon writes a heartbeat bead; if a daemon's heartbeat goes stale, the others detect it

Shutdown¶

• Graceful shutdown: complete current patrol cycle, flush state, exit
• Forced shutdown: kill signal; state recovered from Beads on restart
• Daemons are stateless in memory — all persistent state in Dolt/Beads

Interaction Patterns¶

         ┌──────────┐
         │   Mayor  │  (user intent)
         └────┬─────┘
              │ epic
              ▼
         ┌──────────┐
         │ Refinery │  (decompose → beads)
         └────┬─────┘
              │ bead sequence
              ▼
    ┌─────────────────────┐
    │   Polecats / Crew   │  (execute beads)
    └──┬──────────────┬───┘
       │              │
       ▼              ▼
  ┌─────────┐   ┌──────────┐
  │  Deacon │   │  Witness │
  │ (patrol)│   │ (audit)  │
  └────┬────┘   └────┬─────┘
       │              │
       ▼              ▼
  [stale alert]  [quality alert]
       │              │
       └──────┬───────┘
              ▼
         ┌─────────┐
         │  Mayor  │  (surface to human)
         └─────────┘

Key Interaction: Deacon ↔ Polecats¶

Deacon patrols all polecat hooks. When a polecat's bead times out, Deacon kills the polecat and re-queues the bead. Refinery then reassigns it.

Key Interaction: Witness ↔ Crew¶

Witness audits crew output continuously. When it detects drift, it writes a quality alert bead. The Mayor reads this and decides whether to surface it to the human or let the crew self-correct.

Key Interaction: Refinery ↔ Mayor¶

Mayor receives human intent, passes it to Refinery for decomposition. Refinery returns a bead sequence. Mayor confirms or adjusts before beads are released to polecats.

Key Interaction: Boot ↔ Deacon¶

Boot handles heartbeat traffic. Deacon only sees non-routine signals (timeouts, errors). This keeps Deacon's patrol loop fast and focused.

Shared Conventions¶

All Daemons¶

• Written in Go (deterministic, no LLM, no stochastic behavior)
• State persisted in Dolt/Beads (not in-memory)
• Health via heartbeat beads (each daemon writes its own)
• Configuration via shared TOML/YAML config file
• Logging to structured JSON (for machine queryability)
• Graceful shutdown with state flush

Naming Convention¶

All daemon names are from the Gas Town universe. See gas-town-naming-conventions for the full naming map.

Infrastructure vs Agent Boundary¶

Daemons are infrastructure. Agents are intelligence. Daemons enforce rules; agents make decisions. This separation is deliberate — you want your patrol logic to be deterministic, not creative.

Kelly Adoption Notes¶

From kelly-gas-town-gap-analysis, the daemon architecture has Medium adoption potential for Kelly:

The highest-value near-term adoption is the Deacon's structural liveness enforcement — replacing Kelly's file-based heartbeat with a daemon that actively patrols running agents.

Related Articles¶

kelly-deacon-architecture, gas-town-naming-conventions, gas-town-mayor-pattern, steve-yegge-gas-town, steve-yegge-gupp, steve-yegge-hierarchy, kelly-gas-town-gap-analysis, kelly-router

Source Attribution¶

• Steve Yegge, "Welcome to Gas Town," Jan 1, 2026 — daemon roles introduced
• Steve Yegge, "Gas Town: from Clown Show to v1.0," Apr 3, 2026 — Deacon maturity, worker corpses
• kelly-gas-town-gap-analysis — Kelly comparison for each daemon role
• steve-yegge-gupp — GUPP as the principle Deacon enforces