Documentation
¶
Overview ¶
Package session provides polecat session lifecycle management.
Package session provides polecat session lifecycle management.
Package session provides polecat session lifecycle management.
Package session provides polecat session lifecycle management.
Index ¶
- Constants
- func CrewSessionName(rig, name string) string
- func DeaconSessionName() string
- func FormatStartupNudge(cfg StartupNudgeConfig) string
- func MayorSessionName() string
- func PolecatSessionName(rig, name string) string
- func PropulsionNudge() string
- func PropulsionNudgeForRole(role, workDir string) string
- func RefinerySessionName(rig string) string
- func StartupNudge(t *tmux.Tmux, session string, cfg StartupNudgeConfig) error
- func StopTownSession(t *tmux.Tmux, ts TownSession, force bool) (bool, error)
- func WitnessSessionName(rig string) string
- type AgentIdentity
- type Role
- type StartupNudgeConfig
- type TownSession
Constants ¶
const HQPrefix = "hq-"
HQPrefix is the prefix for town-level services (Mayor, Deacon).
const Prefix = "gt-"
Prefix is the common prefix for rig-level Gas Town tmux sessions.
Variables ¶
This section is empty.
Functions ¶
func CrewSessionName ¶
CrewSessionName returns the session name for a crew worker in a rig.
func DeaconSessionName ¶
func DeaconSessionName() string
DeaconSessionName returns the session name for the Deacon agent. One deacon per machine - multi-town requires containers/VMs for isolation.
func FormatStartupNudge ¶
func FormatStartupNudge(cfg StartupNudgeConfig) string
FormatStartupNudge builds the formatted startup nudge message. Separated from StartupNudge for testing and reuse.
func MayorSessionName ¶
func MayorSessionName() string
MayorSessionName returns the session name for the Mayor agent. One mayor per machine - multi-town requires containers/VMs for isolation.
func PolecatSessionName ¶
PolecatSessionName returns the session name for a polecat in a rig.
func PropulsionNudge ¶
func PropulsionNudge() string
PropulsionNudge generates the GUPP (Gas Town Universal Propulsion Principle) nudge. This is sent after the beacon to trigger autonomous work execution. The agent receives this as user input, triggering the propulsion principle: "If work is on your hook, YOU RUN IT."
func PropulsionNudgeForRole ¶
PropulsionNudgeForRole generates a role-specific GUPP nudge. Different roles have different startup flows: - polecat/crew: Check hook for slung work - witness/refinery: Start patrol cycle - deacon: Start heartbeat patrol - mayor: Check mail for coordination work
The workDir parameter is used to locate .runtime/session_id for including session ID in the message (for Cursor /resume picker discovery).
func RefinerySessionName ¶
RefinerySessionName returns the session name for a rig's Refinery agent.
func StartupNudge ¶
func StartupNudge(t *tmux.Tmux, session string, cfg StartupNudgeConfig) error
StartupNudge sends a formatted startup message to a Cursor session. The message becomes the session title in Cursor's /resume picker, enabling workers to discover sessions.
Format: [GAS TOWN] <recipient> <- <sender> • <timestamp> • <topic[:mol-id]>
Examples:
- [GAS TOWN] gastown/crew/gus <- deacon • 2025-12-30T15:42 • assigned:gt-abc12
- [GAS TOWN] deacon <- mayor • 2025-12-30T08:00 • cold-start
- [GAS TOWN] gastown/witness <- self • 2025-12-30T14:00 • handoff
The message content doesn't trigger GUPP - settings and hooks handle that. The metadata makes sessions identifiable in /resume.
func StopTownSession ¶
StopTownSession stops a single town-level tmux session. If force is true, skips graceful shutdown (Ctrl-C) and kills immediately. Returns true if the session was running and stopped, false if not running.
func WitnessSessionName ¶
WitnessSessionName returns the session name for a rig's Witness agent.
Types ¶
type AgentIdentity ¶
type AgentIdentity struct {
Role Role // mayor, deacon, witness, refinery, crew, polecat
Rig string // rig name (empty for mayor/deacon)
Name string // crew/polecat name (empty for mayor/deacon/witness/refinery)
}
AgentIdentity represents a parsed Gas Town agent identity.
func ParseSessionName ¶
func ParseSessionName(session string) (*AgentIdentity, error)
ParseSessionName parses a tmux session name into an AgentIdentity.
Session name formats:
- hq-mayor → Role: mayor (town-level, one per machine)
- hq-deacon → Role: deacon (town-level, one per machine)
- gt-<rig>-witness → Role: witness, Rig: <rig>
- gt-<rig>-refinery → Role: refinery, Rig: <rig>
- gt-<rig>-crew-<name> → Role: crew, Rig: <rig>, Name: <name>
- gt-<rig>-<name> → Role: polecat, Rig: <rig>, Name: <name>
For polecat sessions without a crew marker, the last segment after the rig is assumed to be the polecat name. This works for simple rig names but may be ambiguous for rig names containing hyphens.
func (*AgentIdentity) Address ¶
func (a *AgentIdentity) Address() string
Address returns the mail-style address for this identity. Examples:
- mayor → "mayor"
- deacon → "deacon"
- witness → "gastown/witness"
- refinery → "gastown/refinery"
- crew → "gastown/crew/max"
- polecat → "gastown/polecats/Toast"
func (*AgentIdentity) GTRole ¶
func (a *AgentIdentity) GTRole() string
GTRole returns the GT_ROLE environment variable format. This is the same as Address() for most roles.
func (*AgentIdentity) SessionName ¶
func (a *AgentIdentity) SessionName() string
SessionName returns the tmux session name for this identity.
type StartupNudgeConfig ¶
type StartupNudgeConfig struct {
// Recipient is the address of the agent being nudged.
// Examples: "gastown/crew/gus", "deacon", "gastown/witness"
Recipient string
// Sender is the agent initiating the nudge.
// Examples: "mayor", "deacon", "self" (for handoff)
Sender string
// Topic describes why the session was started.
// Examples: "cold-start", "handoff", "assigned", or a mol-id
Topic string
// MolID is an optional molecule ID being worked.
// If provided, appended to topic as "topic:mol-id"
MolID string
}
StartupNudgeConfig configures a startup nudge message.
type TownSession ¶
type TownSession struct {
Name string // Display name (e.g., "Mayor")
SessionID string // Tmux session ID (e.g., "hq-mayor")
}
TownSession represents a town-level tmux session.
func TownSessions ¶
func TownSessions() []TownSession
TownSessions returns the list of town-level sessions in shutdown order. Order matters: Boot (Deacon's watchdog) must be stopped before Deacon, otherwise Boot will try to restart Deacon.
Source Files