ADR-0026: Gas City is the Runtime; Gastown is Configuration¶
| Field | Value |
|---|---|
| Status | Accepted |
| Date | 2026-08-26 |
| Author | BLU (lead architect) |
| Approver | Thomas Scola |
| Scope | Platform-wide — orchestration, agent roles, work graph |
| Related | ADR-0022 (Gas City as foundation), ADR-0024, ADR-0025 |
The rule¶
Bluefly runs Gas City as the sole orchestration runtime. The official Gastown pack may be imported as a Gas City configuration to provide the Mayor / Deacon / Witness / Refinery / Polecat operating model.
gt, Gas Town runtime stores, supervisors, path-derived identity, and~/gtruntime authority are not used.
GASTOWN_AS_CONFIGURATION = YES
GASTOWN_AS_RUNTIME = NO
Context¶
The confusion this record ends is real and it has cost time repeatedly: seeing a MAYOR or REFINERY agent led people to conclude Bluefly was running Gas Town, and seeing Gas City led others to conclude the familiar roles were obsolete. Both readings are wrong, and the question "Gas City or Gastown?" is itself malformed.
Upstream states the position directly: Gas City is the platform the Gas Town machinery was extracted into. Every familiar Gas Town role is now configuration, not a built-in orchestrator type. Mayor, Deacon, Witness, Refinery, Polecat, Crew, Dog and Boot are not hardcoded Gas City types — they are agents a pack defines.
So a MAYOR session is not evidence of Gas Town. It is evidence of a configured Gas City agent. What would be evidence of Gas Town is gt running as a control plane, a Gas Town store treated as the work authority, or identity inferred from a ~/gt path.
Decision¶
| Concern | Authority |
|---|---|
| Runtime platform | Gas City |
| CLI | gc |
| Orchestrator | Gas City — desired→running reconciliation, session scaling, health patrol, restart/backoff, order evaluation, ephemeral cleanup |
| Work graph | Beads/Dolt through configured Gas City providers |
| Operating model (roles) | Official Gastown pack, imported and pinned |
| Gas Town runtime | Not authority. Not a store, not a supervisor, not a fallback |
Consequences that follow, and are not optional¶
- Import the official pack; never fork or vendor it. Ordinary differences are patches and overrides. A fork requires a proven upstream gap.
- Pin immutably. A
sha:pin, never@main, never a registry handle in authored TOML — and per ADR-0025, the pinned commit must be reachable from a branch or tag. - The orchestrator owns infrastructure behaviour. Custom watchdog agents, restart loops, session keepalives, job pollers and garbage collectors that duplicate it are deleted, not maintained.
- Prefer Orders and Formulas to standing agents. Before adding another always-running agent, ask whether it is an exec order (deterministic work) or a formula order (agent judgment). Formula v2 fans work across many agents outside a single session, with dependency gating and retry to completion.
- City-scoped and rig-scoped roles are distinct. City: mayor, deacon, boot, dog. Rig: witness, refinery, polecat. City roles are not instantiated per rig; rig roles are not global daemons.
defaults.rig.importsstamps rig behaviour onto new rigs automatically. Defaults first, patch exceptions — never config copied into fifty rig blocks.- Identity is explicit, never path-derived. Not from cwd, not from a directory name. Path is an implementation detail.
MAYOR != GAS_CITY. Mayor is one session and a human entry point. The orchestrator runs the fleet behind it, and durable work survives any session ending.
What this makes possible¶
Fifty developers must not mean fifty hand-built agent environments. It means one configured city, durable work in Beads, scalable transient agent pools per rig, persistent named agents only where persistent identity genuinely matters, and formulas and orders driving parallel work across the graph.
The same shape carries to customer cities: the reusable unit is the pack, the deployment unit is the city, and customer specifics live in city.toml and deployment overlays. The platform is never forked per customer.
Consequences¶
Terminology stops being ambiguous, which is the point — this record exists so that no future reader has to reconstruct the distinction from role names. Seeing Gastown vocabulary in Bluefly's configuration is correct and expected. Seeing gt in Bluefly's runtime is a defect.
Point 8 is recorded because it was learned expensively: four agent sessions ended mid-task in a single night. Durable work survived every one of them; in-progress reasoning survived none. A model in which a role's authority lives in a session is a model that loses work on every restart.