Town-scoped role for cross-rig scatter-gather analysis

[bitlyrist]

Challenge

I have a collection of scan, triage, and remediation agents/skills to perform deep analysis and resolve vulnerabilities semi-autonomously today, but I am looking for opportunities where I no longer need to be a hands on orchestrator. When attempting to POC Gas Town as that orchestration framework, I quickly ran into limitations with triage.

Gas Town currently does not have a role that combines town scope (cross-rig access) with reasoning-class agent resolution. This creates a gap for any workflow that requires analyzing a signal across multiple rigs and synthesizing findings into a unified assessment.

The current model: rigs model code, not runtime

Rigs reflect repository/code structure — and that's the right design for development work. But many investigative tasks require mapping runtime behaviour onto code: tracing a request from a UI component through an API gateway, across internal services, into a data layer — each living in a different repo and therefore a different rig.

No single rig-scoped agent can follow that path. The agent that understands the frontend can't see the backend API. The agent that sees the API can't trace into the internal service. The call chain that matters at runtime is fragmented across the code boundaries that define rig scope and when working on large complex systems multi-rig context significantly improves the quality of analysis.

The pattern that doesn't work today

Given a signal — a vulnerability report, production incident, performance regression, or user-reported issue — the natural workflow is:

1. Receive signal — a bead or external trigger describes the problem
2. Scatter — dispatch rig-scoped investigations across relevant rigs
3. Gather — collect findings back via beads/mail
4. Synthesize — reason across all rig findings to produce a unified analysis (scope, impact, root cause, remediation) and produce a plan

Step 4 is the blocker. No current role can hold cross-rig context and reason about it with a capable model.

Why existing roles don't fit

Role	Scope	Model	Where the challenge is
Polecat	Rig-locked	Full resolution	Can reason deeply but only sees one rig. Can't follow a call chain across repos.
Crew	Rig-locked	Full resolution	Same as polecat — persistent but rig-scoped.
Dog	Town	Haiku (hardcoded)	Has cross-rig access but can't reason. loader.go:1578-1586 returns claudeHaikuPreset() unless there's a non-Claude override. gt prime also appears to render directives and context in a way that makes analysis ineffective- this could be user error or a symptom of the Haiku model though.
Mayor	Town	Configurable	Designed for task decomposition and dispatch, not deep analytical work. Using it for synthesis overloads its coordination role. The Mayor works best when the plan already exists.
Deacon	Town	Configurable	Continuous patrol loop. Not designed for on-demand investigation with a defined lifecycle.
Overseer (#2807)	Town	TBD	Schedules formulas but delegates execution to polecats — same rig-lock problem at the execution layer.

Why MEOW doesn't solve this

MEOW handles steps 1-3 well — the Mayor can break down work and dispatch polecats per rig but MEOW appears to assume a well defined plan already exists and synthesizing a complex plan requires a single agent that:

• Holds findings from all rigs simultaneously
• Reasons about cross-rig relationships (call chains, shared dependencies, propagation paths)
• Maps runtime behaviour back onto code structure across repo boundaries
• Produces a coherent unified assessment

The Mayor could attempt synthesis, but it's optimized for coordination, not analysis. And polecat findings flowing back through beads/mail lose the cross-rig context that a single agent with full visibility would naturally maintain.

Concrete example: business logic bypass in a microservices environment

A security researcher reports a business logic bypass. The vulnerable flow spans:

• UI rig — React app with client-side validation and role-based UI gating
• API gateway rig — externally-facing API that accepts requests and routes to internal services
• Authorization service rig — authorization logic service that enforces (or fails to enforce) course-grained authorization rules
• Internal service rig — business logic service that enforces (or fails to enforce) fine-grained authorization rules
• Data layer rig — persistence layer with its own access control model

The investigation needs to:

1. Trace the full call chain from the UI action through the gateway, into the internal service, down to the data mutation
2. Identify where authorization is checked at each layer and where it's assumed from a previous layer
3. Determine whether the bypass exists because the UI gates a flow that the API doesn't independently enforce
4. Assess whether the internal service is directly reachable (is it actually internal, or exposed via another path?)
5. Map the runtime request flow onto the code in each repo to identify the specific functions/endpoints involved
6. Write a unified assessment covering the full attack surface across all four codebases

No single rig-scoped agent can do this. A polecat in the API gateway rig can find the endpoint but can't see whether the internal service independently validates. A polecat in the UI rig can find the client-side check but can't confirm whether it's the only enforcement point. The investigation requires cross-repo reasoning about runtime behaviour — exactly the gap between how rigs are structured (by code) and how the problem manifests (by request flow).

Today this requires either: (a) 4 separate polecat investigations with manual human synthesis, or (b) dispatching to a dog that has cross-rig access but runs Haiku and can't perform the analysis.

Proposal: Town-scoped analysis role — "Surveyor" (working name)

Naming caveat: "Surveyor" is a placeholder, I am indifferent to the name selected (surveyor, analyst, architect, planner, industrial engineer, etc.). The concept matters more in my projects than the name — it will be used as a working name below though.

A new role designed for the scatter-gather pattern — on-demand, town-scoped, reasoning-class. It produces a proposal and plan for the Mayor based on cross-rig investigation and injected business context.

Design principles

• Town scope — access to all rigs, like dogs and the deacon- the contents of the bead will determine the required rigs at runtime
• Full agent resolution — respects RoleAgents, DefaultAgent, and the intelligent routing system ([enhancement] Intelligent Agent Routing #2784) without a hardcoded Haiku gate
• On-demand lifecycle — spawned for a specific investigation, not a continuous patrol. Closer to a polecat's ephemeral model than a crew member's persistent one
• Scatter-gather native — first-class support for dispatching sub-investigations to rig-scoped agents and collecting results

Session model

Surveyor (reasoning model, cross-rig context)
    |
    +---> Polecat on ui-rig         (trace client-side flow)
    +---> Polecat on api-gateway    (trace endpoint + routing)
    +---> Polecat on authz-svc    (trace authz framework + course-grained authz)
    +---> Polecat on internal-svc   (trace business logic + fine-grained authz)
    +---> Polecat on data-layer     (trace access control model)
    |
    <--- Gather findings via beads/mail
    |
    +---> Synthesize: map runtime call chain across all four codebases
    +---> Produce proposal for Mayor with unified assessment

Lifecycle

1. Signal arrives (slung bead with analysis formula, mail from mayor/deacon, external trigger)
2. Session starts with reasoning-class model
3. Reads the signal, determines which rigs are relevant
4. Dispatches rig-scoped polecats via gt sling (scatter)
5. Monitors polecat completion via convoy or mail (gather)
6. Synthesizes findings — maps runtime behaviour onto code structure across rigs
7. Produces a proposal for the Mayor: unified assessment, recommended actions, remediation plan
8. Writes results to bead, delivers proposal via mail, session terminates

Runtime context

The surveyor needs to understand how rigs relate at runtime (service dependencies, API boundaries, what's internal vs external). This context is user-provided via existing mechanisms — CLAUDE.md files, role templates, and formula vars — not new framework features. Gas Town already has the tools for users to introduce domain-specific context; the surveyor just needs to be primed with it the same way any other role is.

Relationship to existing work

Issue	Relationship
#2784 — Intelligent Agent Routing	This role would be a consumer of the routing system. The reasoning tier maps naturally to analysis work.
#2807 — Overseer role	Complementary. Overseer schedules recurring work; this role handles on-demand investigations. Overseer could trigger it.
#303 — Output metadata for synthesis	Directly enables the gather step. This role needs to locate polecat outputs across rigs.
#2815 — Compounds (closed)	Compounds would have provided rig grouping. Without them, this role determines scope from the signal itself or from runtime topology config.
#2531 — RFC: Intelligent Model Routing	This role is a concrete use case for the reasoning tier.

What this unblocks

• Security triage — tracing vulnerabilities across service boundaries (UI → API → internal service → data layer)
• Incident investigation — following a failure through the runtime call chain across repos
• Performance analysis — correlating latency across service boundaries that span rigs
• Impact assessment — understanding how a change in one repo affects runtime behaviour in others
• Any workflow requiring cross-repo reasoning about runtime behaviour mapped onto code structure

Alternatives considered

Upgrade dogs to support reasoning models

Remove the Haiku gate in loader.go so dogs can use any model. Smallest change, but dogs are architecturally "cheap infrastructure workers" — reusing sessions, 2h stuck threshold, fire-and-forget dispatch. Making them also serve as deep-reasoning analysts muddies the abstraction. Business context injection possibly remains a challenge as well.

Mayor does synthesis

The Mayor already has town scope and capable models. After MEOW dispatch, it could gather results and synthesize. But the Mayor is a coordination bottleneck — tying it up with analysis blocks other dispatch work. The Mayor should delegate synthesis, not perform it.

Deacon handles investigation

The Deacon has town scope and runs continuously. But its patrol loop model doesn't fit on-demand investigation — it would need to interrupt its patrol cycle, potentially missing health checks. Different lifecycle, different purpose.

Multi-rig polecat

Extend polecat scope to optionally span multiple rigs. This fundamentally changes the polecat contract (ephemeral, rig-scoped, one task) and creates complexity in worktree management, git context, and bead routing.