Gastown Cloud: Cloud-first rewrite of Gastown as a Kilo platform feature

[jrf0110]

Disclaimer: This is completely experimental. We are currently exploring multiple angles for integration.

Overview

Cloud-first rewrite of Gastown's core tenets as a Kilo platform feature (Proposal D — Revised). All orchestration state lives in Durable Objects (SQLite). Agents interact with Gastown via tool calls backed by DO RPCs — no filesystem coordination, no gt/bd binaries. Each town gets a Cloudflare Container that runs all agent processes (Kilo CLI instances) — one container per town, not one per agent.

Product vision: An absurdly simple product. Create a town, connect repos via existing integrations, talk to the Mayor in a chat interface. The full Gastown machine operates behind the scenes — agents spawn, communicate, merge code — and the UI shows everything happening in real time. Every object on screen is clickable, every connection is traceable.

See plans/gastown-cloud-proposal-d.md for the full architecture proposal, UI vision, and architecture assessment.

---

Workflow

All work for this project lives on the 204-gt-prop-d feature branch. Nothing merges to main.

For each sub-issue:

1. Branch: Create a branch off 204-gt-prop-d using the naming scheme {issue_number}-{short-description}
2. Implement: Work through the issue's acceptance criteria. Write tests alongside the implementation.
3. Validate: Run the test suite and type checks (pnpm typecheck) to confirm everything passes.
4. Commit: Stage all changes and create a commit with a descriptive message referencing the sub-issue number.
5. Push & PR: Push the branch to the remote and create a pull request targeting 204-gt-prop-d (not main). Link the sub-issue in the PR body with Closes #NNN.

---

Phase 1: Core Loop + Mayor (COMPLETED ✅)

Foundation: Rig DO state machine, HTTP API, tool plugin, container with kilo serve, alarm scheduler, tRPC routes, basic dashboard, MayorDO.

• [Gastown] PR 1: Rig Durable Object #208 — PR 1: Rig Durable Object
• [Gastown] PR 2: HTTP API Layer #209 — PR 2: HTTP API Layer
• [Gastown] PR 3: Tool Plugin #210 — PR 3: Tool Plugin
• [Gastown] PR 4: Town Container — Execution Runtime #211 — PR 4: Town Container — Execution Runtime
• [Gastown] PR 5: Rig DO Alarm — Work Scheduler #212 — PR 5: Rig DO Alarm — Work Scheduler
• [Gastown] PR 5.5: Container — Adopt kilo serve for Agent Management #305 — PR 5.5: Container — Adopt kilo serve
• [Gastown] PR 6: tRPC Routes — Town & Rig Management #268 — PR 6: tRPC Routes
• [Gastown] PR 7: Basic Dashboard UI #213 — PR 7: Basic Dashboard UI (skeleton)
• [Gastown] PR 7.5: Agent Lifecycle & Container Reliability Fixes #335 — PR 7.5: Agent Lifecycle & Container Reliability Fixes
• [Gastown] PR 8: MayorDO — Town-Level Conversational Agent #338 — PR 8: MayorDO — Town-Level Conversational Agent

Phase 1.5: Close the Loop + Usable UI (NEW — Priority Sprint)

The core loop is built but doesn't close: the Mayor can't delegate, agents can't be watched, merges 404, and the dashboard is a skeleton. These issues unblock a product that actually works end-to-end.

P0 — Must complete before product is usable:

• [Gastown] PR 8.5: Mayor Tools — Cross-Rig Delegation (P0 — #1 Priority) #339 — Mayor Tools — Cross-Rig Delegation ⚡ Highest priority. Without tools, the Mayor is a chatbot that can't do anything. The chat-first product vision depends entirely on this.
• [Gastown] Agent Streaming Endpoint — Container WebSocket/SSE for Live Agent Observation #343 — Agent Streaming Endpoint ⚡ WebSocket streaming from container through TownContainerDO to browser. PR [Gastown] Agent Streaming Endpoint — WebSocket-based Live Agent Observation #348.
• Mayor agent completes without using tools — missing GASTOWN_SESSION_TOKEN in local dev #349 — Mayor Tool Execution Failures ⚡ Mayor agent starts and has tools registered but completes without using them. Need to diagnose container-side errors when mayor tools (gt_sling, gt_list_rigs, etc.) execute — likely auth or network issue with GASTOWN_API_URL from inside the container.
• [Gastown] Manual Merge Flow — Container /merge Endpoint + Review Queue Processing (P0) #214 — Manual Merge Flow ⚡ The container has no /merge endpoint — the call 404s. The polecat→done→merge→closed loop is broken. Beads in the review queue sit forever.
• [Gastown] Rig DO Event Log — Append-Only Bead Events for Real-Time Dashboard Feed #344 — Rig DO Event Log ⚡ No append-only event stream means no activity feed, no bead timeline, no real-time dashboard. Required for the UI to show "what happened."

P1 — High impact, required for decent UI:

• [Gastown] Wire Detailed Polecat System Prompt #345 — Wire Detailed Polecat System Prompt — Low effort, high impact. A GUPP-aware prompt with tool docs exists but isn't used.
• [Gastown] Dashboard UI Overhaul — Town Home, Mayor Chat, Rig Workbench #346 — Dashboard UI Overhaul — Split-pane town home (Mayor chat + dashboard), rig workbench (bead board, agent roster, stream panel), clickable detail panels. Depends on [Gastown] PR 8.5: Mayor Tools — Cross-Rig Delegation (P0 — #1 Priority) #339, [Gastown] Agent Streaming Endpoint — Container WebSocket/SSE for Live Agent Observation #343, [Gastown] Rig DO Event Log — Append-Only Bead Events for Real-Time Dashboard Feed #344.

Phase 2: Multi-Agent Orchestration (COMPLETED ✅)

All Phase 2 issues implemented in PR #389.

• [Gastown] PR 9: Town Durable Object #215 — Town Durable Object — Cross-rig coordination: convoy lifecycle, escalation routing, watchdog heartbeat.
• [Gastown] PR 10.5: Town Configuration — Environment Variables & Settings #385 — Town Configuration — Environment Variables & Settings — Env var editor, git auth tokens, agent defaults, refinery config, settings page UI.
• [Gastown] PR 10.6: Integrations-Based Repo Connection #386 — Integrations-Based Repo Connection — Repo picker via GitHub/GitLab integrations, platform_integration_id on rigs, self-hosted GitLab support.
• [Gastown] PR 10: Multiple Polecats per Rig #216 — Multiple Polecats per Rig — 20-name pool, configurable concurrency cap, bead-ID branch isolation.
• [Gastown] PR 12: Refinery Agent #218 — Refinery Agent — AI-powered merge review with quality gates, rework requests. Falls back to deterministic merge.
• [Gastown] PR 13: Molecule/Formula System #219 — Molecule/Formula System — Multi-step workflows with gt_mol_current / gt_mol_advance tools, auto-completion.
• [Gastown] PR 14: Convoy Lifecycle #220 — Convoy Lifecycle — Cross-rig batch work tracking with automatic landing detection on bead close.
• [Gastown] PR 15: Escalation System #221 — Escalation System — Severity routing (including critical), auto-re-escalation with 4h spacing, acknowledge flow.

Known issues from Phase 2 testing:

• [Gastown] Polecat stuck in zombie hook state after clone failure causes cascading sling failures #411 — Polecat stuck in zombie hook state after clone failure causes cascading sling failures

Phase 2.5: Town-Centric Refactor

Simplify the DO topology, replace subprocess-based agent management with the SDK, and establish a clean WebSocket event pipeline. See plans/gastown-town-centric-refactor.md for the full plan.

• Town-Centric Refactor: Consolidate control plane into TownDO, SDK-based agents, WebSocket streaming #419 — Town-Centric Refactor — Consolidate all control-plane data into TownDO (eliminate Rig DO + Mayor DO), SDK-based agents (createOpencode() replaces Bun.spawn), WebSocket streaming (eliminate SSE + polling + tickets), per-agent AgentDO for event storage, config-on-request (eliminate stale container injection), proactive container/mayor startup. PR refactor(gastown): Town-centric refactor — Phase A: Consolidate control plane (#419) #421.
• Make Cloud Gastown beads-centric: unify all object types into the beads primitive #441 — Beads-Centric Data Model — Unify all object types (mail, molecules, convoys, escalations, merge requests, agents) into the universal beads primitive with satellite metadata tables. Drop rig_mail, rig_molecules, rig_review_queue, town_convoys, town_convoy_beads, town_escalations, rig_agents. Add parent_bead_id, bead_dependencies table, entity-prefixed column naming.
• Fix: Polecat agents cannot push — git credentials never populated in town config #443 — Fix: Polecat git push credentials — Git credentials are never populated in town config. The tRPC createRig doesn't set git_auth.github_token, so GIT_TOKEN is never passed to the container. Agents clone public repos fine but can't push. Fix: populate git credentials from integration tokens on rig creation, add token refresh, fix merge dispatch for self-hosted GitLab.
• Embed agent terminal UI via xterm.js + container PTY proxy #450 — Agent Terminal UI (xterm.js) — Embed live terminal view of agent sessions via xterm.js connected to the container's existing PTY infrastructure. Proxy PTY WebSocket through control-server → TownContainerDO → worker → browser. Enables direct visibility into agent work and interactive agent sessions from the dashboard.
• [Gastown] Dashboard Deep Drill-Down — Visualization, Conversation History, Cost Tracking #225 — Dashboard Deep Drill-Down — Convoy visualization, conversation history/replay, topology view, cost tracking.

Phase 3: Multi-Rig + Scaling

• Gate Gastown UI to Kilo admins only #537 — Gate Gastown UI to Kilo Admins — Restrict all Gastown pages, tRPC procedures, and nav items to is_admin users only. Temporary gate until Gastown is ready for beta/GA.
• Bug: Refinery agent dispatched to wrong rig in multi-rig towns #657 — Bug: Refinery dispatched to wrong rig — Four compounding bugs cause the refinery to clone the wrong rig's repo in multi-rig towns: singleton reuse ignores rig_id, processReviewQueue hardcodes rigList[0], merge_request beads have null rig_id, ReviewQueueInput has no rig_id field.
• Configurable merge strategy: direct push vs pull request #473 — Configurable Merge Strategy — Support direct (Refinery pushes to main) and pr (Refinery creates a GitHub/GitLab PR for human review) merge strategies. Configurable at town level with per-rig overrides. PR strategy includes quality gate results, agent attribution, and webhook-based status tracking.
• Wire convoys end-to-end: batch sling, Mayor tools, and dead code cleanup #540 — Wire Convoys End-to-End — Add gt_sling_batch tool for atomic multi-bead + convoy creation, gt_list_convoys and gt_convoy_status visibility tools, Mayor prompt updates, and dead code cleanup. Backend convoy infrastructure (createConvoy, onBeadClosed, landing detection) already works — this connects it to the Mayor.
• Witness & Deacon: Alarm-driven orchestration with on-demand LLM triage #442 — Witness & Deacon: Alarm-Driven Orchestration — Run all mechanical witness/deacon patrol behaviors (protocol mail flow, zombie detection, GUPP violations, convoy completion, stale hooks, gate evaluation) as deterministic code in the TownDO alarm. Spawn short-lived LLM triage agents only for ambiguous situations (dirty polecat triage, stuck agent inspection, help requests). Replaces persistent AI patrol loops with alarm + on-demand reasoning.
• [Gastown] PR 16: Multi-Rig Support #223 — Multi-Rig Support — Multiple rigs per town, cross-rig mail routing, multi-rig dashboard.
• [Gastown] PR 17: Agent CVs & Performance Analytics #224 — Agent CVs & Performance Analytics — Agent Identity DO, work ledger, performance cards.
• [Gastown] PR 18: Container Resilience — Checkpoint/Restore #269 — Container Resilience — Checkpoint/Restore — Ephemeral disk recovery, git state restoration.

Phase 4: Hardening

• [Gastown] PR 20: Stress Testing #226 — Stress Testing — 30 concurrent polecats, latency benchmarks, resource limits.
• [Gastown] PR 21: Edge Case Handling #227 — Edge Case Handling — Split-brain, container OOM, crash recovery.
• [Gastown] PR 22: Observability #228 — Observability — Structured logging, event streaming, alerting, usage metrics.
• [Gastown] Onboarding Flow — Zero to Agent in Under 2 Minutes #229 — Onboarding Flow — Zero to agent in under 2 minutes wizard.
• [Gastown] PR 24: Postgres Replication Layer #230 — Postgres Replication Layer — Read replica, sync-on-write, migrate dashboard reads.
• [Gastown] PR 25: Documentation & API Reference #231 — Documentation & API Reference

---

Future Ideas

• Cloud Gastown: Future ideas — capabilities unique to or enhanced by the cloud model #447 — Cloud-Unique Capabilities — Ideas for features that are impossible or dramatically better in the cloud: shared towns, agent marketplace, cross-session intelligence, cost attribution/budget controls, speculative execution, webhook-driven beads, persistent agent reputation, local CLI bridge.

---

Closed/Superseded Issues

• [Gastown] PR 10: Witness Alarm #217 — Witness Alarm — Folded into [Gastown] PR 5: Rig DO Alarm — Work Scheduler #212 (Rig DO Alarm). The witness patrol is part of the alarm handler.
• [Gastown] PR 11: Mayor Agent #222 — Mayor Agent (old design) — Superseded by [Gastown] PR 8: MayorDO — Town-Level Conversational Agent #338 (MayorDO).