cmd

package
v0.0.0-...-5502a72 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 16, 2026 License: MIT Imports: 64 Imported by: 0

Documentation

Overview

Package cmd provides CLI commands for the gt tool.

Package cmd provides CLI commands for the gt tool.

Package cmd provides CLI commands for the gt tool.

Package cmd provides polecat spawning utilities for gt sling.

Package cmd provides CLI commands for the gt tool.

Package cmd provides CLI commands for the gt tool. This file implements the gt rig config commands for viewing and manipulating rig configuration across property layers.

Package cmd provides CLI commands for the gt tool.

Index

Constants

View Source 
const (
	ExitCompleted     = "COMPLETED"
	ExitEscalated     = "ESCALATED"
	ExitDeferred      = "DEFERRED"
	ExitPhaseComplete = "PHASE_COMPLETE"
)

Valid exit types for gt done

View Source 
const (
	// SeverityCritical (P0) - System-threatening issues requiring immediate human attention.
	// Examples: data corruption, security breach, complete system failure.
	SeverityCritical = "CRITICAL"

	// SeverityHigh (P1) - Important blockers that need human attention soon.
	// Examples: unresolvable merge conflicts, critical blocking bugs, ambiguous requirements.
	SeverityHigh = "HIGH"

	// SeverityMedium (P2) - Standard escalations for human attention at convenience.
	// Examples: unclear requirements, design decisions needed, non-blocking issues.
	SeverityMedium = "MEDIUM"
)

Escalation severity levels. These map to mail priorities and indicate urgency for human attention.

View Source 
const (
	EnvGTRole     = "GT_ROLE"
	EnvGTRoleHome = "GT_ROLE_HOME"
)

Environment variables for role detection

View Source 
const (
	GroupWork      = "work"
	GroupAgents    = "agents"
	GroupComm      = "comm"
	GroupServices  = "services"
	GroupWorkspace = "workspace"
	GroupConfig    = "config"
	GroupDiag      = "diag"
)

Command group IDs - used by subcommands to organize help output

View Source 
const HQGitignore = `` /* 1894-byte string literal not displayed */

HQGitignore is the standard .gitignore for Gas Town HQs

View Source 
const MinBeadsVersion = "0.47.0"

MinBeadsVersion is the minimum required beads version for Gas Town. This version must include custom type support (bd-i54l).

View Source 
const RigDockedLabel = "status:docked"

RigDockedLabel is the label set on rig identity beads when docked.

View Source 
const RigStatusKey = "status"

RigStatusKey is the wisp config key for rig operational status.

View Source 
const RigStatusParked = "parked"

RigStatusParked is the value indicating a rig is parked.

Variables

View Source 
var (
	Version = "0.2.6"
	// Build can be set via ldflags at compile time
	Build = "dev"
	// Commit and Branch - the git revision the binary was built from (optional ldflag)
	Commit = ""
	Branch = ""
)

Version information - set at build time via ldflags

View Source 
var AgentTypeColors = map[AgentType]string{
	AgentMayor:    "#[fg=red,bold]",
	AgentDeacon:   "#[fg=yellow,bold]",
	AgentWitness:  "#[fg=cyan]",
	AgentRefinery: "#[fg=blue]",
	AgentCrew:     "#[fg=green]",
	AgentPolecat:  "#[fg=white,dim]",
}

AgentTypeColors maps agent types to tmux color codes.

View Source 
var AgentTypeIcons = map[AgentType]string{
	AgentMayor:    constants.IconMayor,
	AgentDeacon:   constants.IconDeacon,
	AgentWitness:  constants.IconWitness,
	AgentRefinery: constants.IconRefinery,
	AgentCrew:     constants.IconCrew,
	AgentPolecat:  constants.IconPolecat,
}

AgentTypeIcons maps agent types to display icons. Uses centralized icons from constants package.

Functions

func CheckBeadsVersion 

func CheckBeadsVersion() error

CheckBeadsVersion verifies that the installed beads version meets the minimum requirement. Returns nil if the version is sufficient, or an error with details if not. This function is cached and only runs once per process.

func CheckSynthesisReady 

func CheckSynthesisReady(convoyID string) (bool, error)

CheckSynthesisReady checks if a convoy is ready for synthesis. Returns true if all tracked legs are complete.

func Execute 

func Execute() int

Execute runs the root command and returns an exit code. The caller (main) should call os.Exit with this code.

func GetCurrentStepBackoff 

func GetCurrentStepBackoff(workDir string) (*beads.BackoffConfig, error)

GetCurrentStepBackoff retrieves backoff config from the current step. This is used by patrol agents to get the timeout for await-signal.

func InitGitForHarness 

func InitGitForHarness(hqRoot string, github string, private bool) error

InitGitForHarness is the shared implementation for git initialization. It can be called from both 'gt git-init' and 'gt install --git'. Note: Function name kept for backwards compatibility.

func InvalidateBeadsVersionCache 

func InvalidateBeadsVersionCache()

InvalidateBeadsVersionCache removes the cached version check. Useful when upgrading beads or debugging.

func IsDogTarget 

func IsDogTarget(target string) (dogName string, isDog bool)

IsDogTarget checks if target is a dog target pattern. Returns the dog name (or empty for pool dispatch) and true if it's a dog target. Patterns:

  • "deacon/dogs" -> ("", true) - dispatch to any idle dog
  • "deacon/dogs/alpha" -> ("alpha", true) - dispatch to specific dog

func IsRigDocked 

func IsRigDocked(townRoot, rigName, prefix string) bool

IsRigDocked checks if a rig is docked by checking for the status:docked label on the rig identity bead. This function is exported for use by the daemon.

func IsRigName 

func IsRigName(target string) (string, bool)

IsRigName checks if a target string is a rig name (not a role or path). Returns the rig name and true if it's a valid rig.

func IsRigParked 

func IsRigParked(townRoot, rigName string) bool

IsRigParked checks if a rig is parked in the wisp layer. This function is exported for use by the daemon.

func IsSilentExit 

func IsSilentExit(err error) (int, bool)

IsSilentExit checks if an error is a SilentExitError and returns its code. Returns 0 and false if err is nil or not a SilentExitError.

func LogCrash 

func LogCrash(townRoot, agent, reason string) error

LogCrash logs a crash event.

func LogDone 

func LogDone(townRoot, agent, issueID string) error

LogDone logs a done event.

func LogEvent 

func LogEvent(eventType townlog.EventType, agent, context string) error

LogEvent is a helper that logs an event from anywhere in the codebase. It finds the town root and logs the event.

func LogEventWithRoot 

func LogEventWithRoot(townRoot string, eventType townlog.EventType, agent, context string) error

LogEventWithRoot logs an event when the town root is already known.

func LogHandoff 

func LogHandoff(townRoot, agent, context string) error

LogHandoff logs a handoff event.

func LogKill 

func LogKill(townRoot, agent, reason string) error

LogKill logs a kill event.

func LogNudge 

func LogNudge(townRoot, agent, message string) error

LogNudge logs a nudge event.

func LogSpawn 

func LogSpawn(townRoot, agent, issueID string) error

LogSpawn logs a spawn event.

func LogWake 

func LogWake(townRoot, agent, context string) error

LogWake logs a wake event.

func ReadPersistedSessionID 

func ReadPersistedSessionID() string

ReadPersistedSessionID reads a previously persisted session ID. Checks cwd first, then town root. Returns empty string if not found.

func TriggerSynthesisIfReady 

func TriggerSynthesisIfReady(convoyID, targetRig string) error

TriggerSynthesisIfReady checks convoy status and starts synthesis if ready. This can be called by the witness when a leg completes.

Types

type AccountListItem 

type AccountListItem struct {
	Handle      string `json:"handle"`
	Email       string `json:"email"`
	Description string `json:"description,omitempty"`
	ConfigDir   string `json:"config_dir"`
	IsDefault   bool   `json:"is_default"`
}

AccountListItem represents an account in list output.

type AgentHookInfo 

type AgentHookInfo struct {
	Agent    string `json:"agent"`              // Agent address (e.g., "greenplace/toast", "greenplace/witness")
	Role     string `json:"role"`               // Role type (polecat, crew, witness, refinery)
	HasWork  bool   `json:"has_work"`           // Whether agent has pinned work
	Molecule string `json:"molecule,omitempty"` // Attached molecule ID
	Title    string `json:"title,omitempty"`    // Pinned bead title
}

AgentHookInfo represents an agent's hook (pinned work) status.

type AgentListItem 

type AgentListItem struct {
	Name     string `json:"name"`
	Command  string `json:"command"`
	Args     string `json:"args,omitempty"`
	Type     string `json:"type"` // "built-in" or "custom"
	IsCustom bool   `json:"is_custom"`
}

AgentListItem represents an agent in list output.

type AgentRuntime 

type AgentRuntime struct {
	Name         string `json:"name"`                    // Display name (e.g., "mayor", "witness")
	Address      string `json:"address"`                 // Full address (e.g., "greenplace/witness")
	Session      string `json:"session"`                 // tmux session name
	Role         string `json:"role"`                    // Role type
	Running      bool   `json:"running"`                 // Is tmux session running?
	HasWork      bool   `json:"has_work"`                // Has pinned work?
	WorkTitle    string `json:"work_title,omitempty"`    // Title of pinned work
	HookBead     string `json:"hook_bead,omitempty"`     // Pinned bead ID from agent bead
	State        string `json:"state,omitempty"`         // Agent state from agent bead
	UnreadMail   int    `json:"unread_mail"`             // Number of unread messages
	FirstSubject string `json:"first_subject,omitempty"` // Subject of first unread message
}

AgentRuntime represents the runtime state of an agent.

type AgentSession 

type AgentSession struct {
	Name      string
	Type      AgentType
	Rig       string // For rig-specific agents
	AgentName string // e.g., crew name, polecat name
}

AgentSession represents a categorized tmux session.

type AgentType 

type AgentType int

AgentType represents the type of Gas Town agent. 

const (
	AgentMayor AgentType = iota
	AgentDeacon
	AgentWitness
	AgentRefinery
	AgentCrew
	AgentPolecat
)

type AuditEntry 

type AuditEntry struct {
	Timestamp time.Time `json:"timestamp"`
	Source    string    `json:"source"` // "git", "beads", "townlog", "events"
	Type      string    `json:"type"`   // "commit", "bead_created", "bead_closed", "spawn", etc.
	Actor     string    `json:"actor"`
	Summary   string    `json:"summary"`
	Details   string    `json:"details,omitempty"`
	ID        string    `json:"id,omitempty"` // commit hash, bead ID, etc.
}

AuditEntry represents a single entry in the audit log.

type AwaitSignalResult 

type AwaitSignalResult struct {
	Reason     string        `json:"reason"`                // "signal" or "timeout"
	Elapsed    time.Duration `json:"elapsed"`               // how long we waited
	Signal     string        `json:"signal,omitempty"`      // the line that woke us (if signal)
	IdleCycles int           `json:"idle_cycles,omitempty"` // current idle cycle count (after update)
}

AwaitSignalResult is the result of an await-signal operation.

type CallbackResult 

type CallbackResult struct {
	MessageID    string
	CallbackType CallbackType
	From         string
	Subject      string
	Handled      bool
	Action       string
	Error        error
}

CallbackResult tracks the result of processing a callback.

type CallbackType 

type CallbackType string

CallbackType identifies the type of callback message. 

const (
	CallbackPolecatDone    CallbackType = "polecat_done"
	CallbackMergeRejected  CallbackType = "merge_rejected"
	CallbackMergeCompleted CallbackType = "merge_completed"
	CallbackHelp           CallbackType = "help"
	CallbackEscalation     CallbackType = "escalation"
	CallbackSling          CallbackType = "sling"
	CallbackUnknown        CallbackType = "unknown"
)

type ClaudeHook 

type ClaudeHook struct {
	Type    string `json:"type"`
	Command string `json:"command,omitempty"`
}

ClaudeHook represents an individual hook.

type ClaudeHookMatcher 

type ClaudeHookMatcher struct {
	Matcher string       `json:"matcher"`
	Hooks   []ClaudeHook `json:"hooks"`
}

ClaudeHookMatcher represents a hook matcher entry.

type ClaudeSettings 

type ClaudeSettings struct {
	EnabledPlugins map[string]bool                `json:"enabledPlugins,omitempty"`
	Hooks          map[string][]ClaudeHookMatcher `json:"hooks,omitempty"`
}

ClaudeSettings represents the Claude Code settings.json structure.

type CollisionIssue 

type CollisionIssue struct {
	Type      string `json:"type"` // "stale", "collision", "orphaned"
	WorkerDir string `json:"worker_dir"`
	Message   string `json:"message"`
	PID       int    `json:"pid,omitempty"`
	SessionID string `json:"session_id,omitempty"`
}

CollisionIssue describes a single collision or lock issue.

type CollisionReport 

type CollisionReport struct {
	TotalSessions int                       `json:"total_sessions"`
	TotalLocks    int                       `json:"total_locks"`
	Collisions    int                       `json:"collisions"`
	StaleLocks    int                       `json:"stale_locks"`
	Issues        []CollisionIssue          `json:"issues,omitempty"`
	Locks         map[string]*lock.LockInfo `json:"locks,omitempty"`
}

CollisionReport holds the results of a collision check.

type ConvoyMeta 

type ConvoyMeta struct {
	ID          string   `json:"id"`
	Title       string   `json:"title"`
	Status      string   `json:"status"`
	Formula     string   `json:"formula,omitempty"`      // Formula name
	FormulaPath string   `json:"formula_path,omitempty"` // Path to formula file
	ReviewID    string   `json:"review_id,omitempty"`    // Review ID for output paths
	LegIssues   []string `json:"leg_issues,omitempty"`   // Tracked leg issue IDs
}

ConvoyMeta holds metadata about a convoy including its formula.

type CostEntry 

type CostEntry struct {
	SessionID string    `json:"session_id"`
	Role      string    `json:"role"`
	Rig       string    `json:"rig,omitempty"`
	Worker    string    `json:"worker,omitempty"`
	CostUSD   float64   `json:"cost_usd"`
	StartedAt time.Time `json:"started_at"`
	EndedAt   time.Time `json:"ended_at"`
	WorkItem  string    `json:"work_item,omitempty"`
}

CostEntry is a ledger entry for historical cost tracking.

type CostsOutput 

type CostsOutput struct {
	Sessions []SessionCost      `json:"sessions,omitempty"`
	Total    float64            `json:"total_usd"`
	ByRole   map[string]float64 `json:"by_role,omitempty"`
	ByRig    map[string]float64 `json:"by_rig,omitempty"`
	Period   string             `json:"period,omitempty"`
}

CostsOutput is the JSON output structure.

type CrewListItem 

type CrewListItem struct {
	Name       string `json:"name"`
	Rig        string `json:"rig"`
	Branch     string `json:"branch"`
	Path       string `json:"path"`
	HasSession bool   `json:"has_session"`
	GitClean   bool   `json:"git_clean"`
}

CrewListItem represents a crew worker in list output.

type CrewStatusItem 

type CrewStatusItem struct {
	Name         string   `json:"name"`
	Rig          string   `json:"rig"`
	Path         string   `json:"path"`
	Branch       string   `json:"branch"`
	HasSession   bool     `json:"has_session"`
	SessionID    string   `json:"session_id,omitempty"`
	GitClean     bool     `json:"git_clean"`
	GitModified  []string `json:"git_modified,omitempty"`
	GitUntracked []string `json:"git_untracked,omitempty"`
	MailTotal    int      `json:"mail_total"`
	MailUnread   int      `json:"mail_unread"`
}

CrewStatusItem represents detailed status for a crew worker.

type DependencyInfo 

type DependencyInfo struct {
	ID       string `json:"id"`
	Title    string `json:"title"`
	Status   string `json:"status"`
	Priority int    `json:"priority"`
	Type     string `json:"type"`
}

DependencyInfo represents a dependency or blocker.

type DogDispatchInfo 

type DogDispatchInfo struct {
	DogName string // Name of the dog
	AgentID string // Agent ID format (deacon/dogs/<name>)
	Pane    string // Tmux pane (empty if no session)
	Spawned bool   // True if dog was spawned (new)
}

DogDispatchInfo contains information about a dog dispatch.

func DispatchToDog 

func DispatchToDog(dogName string, create bool) (*DogDispatchInfo, error)

DispatchToDog finds or spawns a dog for work dispatch. If dogName is empty, finds an idle dog from the pool. If create is true and no dogs exist, creates one.

type EventListItem 

type EventListItem struct {
	ID string `json:"id"`
}

EventListItem represents an event from bd list (minimal fields).

type GateWakeResult 

type GateWakeResult struct {
	GateID      string   `json:"gate_id"`
	CloseReason string   `json:"close_reason"`
	Waiters     []string `json:"waiters"`
	Notified    []string `json:"notified"`
	Failed      []string `json:"failed,omitempty"`
}

GateWakeResult represents the result of sending wake mail.

type GitState 

type GitState struct {
	Clean            bool     `json:"clean"`
	UncommittedFiles []string `json:"uncommitted_files"`
	UnpushedCommits  int      `json:"unpushed_commits"`
	StashCount       int      `json:"stash_count"`
}

GitState represents the git state of a polecat's worktree.

type HookInfo 

type HookInfo struct {
	Type     string   `json:"type"`     // Hook type (SessionStart, etc.)
	Location string   `json:"location"` // Path to the settings file
	Agent    string   `json:"agent"`    // Agent that owns this hook (e.g., "polecat/nux")
	Matcher  string   `json:"matcher"`  // Pattern matcher (empty = all)
	Commands []string `json:"commands"` // Hook commands
	Status   string   `json:"status"`   // "active" or "disabled"
}

HookInfo contains information about a discovered hook.

type HooksOutput 

type HooksOutput struct {
	TownRoot string     `json:"town_root"`
	Hooks    []HookInfo `json:"hooks"`
	Count    int        `json:"count"`
}

HooksOutput is the JSON output structure.

type IntegrationStatusMRSummary 

type IntegrationStatusMRSummary struct {
	ID     string `json:"id"`
	Title  string `json:"title"`
	Status string `json:"status,omitempty"`
}

IntegrationStatusMRSummary represents a merge request in the integration status output.

type IntegrationStatusOutput 

type IntegrationStatusOutput struct {
	Epic        string                       `json:"epic"`
	Branch      string                       `json:"branch"`
	Created     string                       `json:"created,omitempty"`
	AheadOfMain int                          `json:"ahead_of_main"`
	MergedMRs   []IntegrationStatusMRSummary `json:"merged_mrs"`
	PendingMRs  []IntegrationStatusMRSummary `json:"pending_mrs"`
}

IntegrationStatusOutput is the JSON output structure for integration status.

type LegOutput 

type LegOutput struct {
	LegID    string `json:"leg_id"`
	Title    string `json:"title"`
	Status   string `json:"status"`
	FilePath string `json:"file_path,omitempty"`
	Content  string `json:"content,omitempty"`
	HasFile  bool   `json:"has_file"`
}

LegOutput represents collected output from a convoy leg.

type MQSummary 

type MQSummary struct {
	Pending  int    `json:"pending"`   // Open MRs ready to merge (no blockers)
	InFlight int    `json:"in_flight"` // MRs currently being processed
	Blocked  int    `json:"blocked"`   // MRs waiting on dependencies
	State    string `json:"state"`     // idle, processing, or blocked
	Health   string `json:"health"`    // healthy, stale, or empty
}

MQSummary represents the merge queue status for a rig.

type MRStatusOutput 

type MRStatusOutput struct {
	// Core issue fields
	ID        string `json:"id"`
	Title     string `json:"title"`
	Status    string `json:"status"`
	Priority  int    `json:"priority"`
	Type      string `json:"type"`
	Assignee  string `json:"assignee,omitempty"`
	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
	ClosedAt  string `json:"closed_at,omitempty"`

	// MR-specific fields
	Branch      string `json:"branch,omitempty"`
	Target      string `json:"target,omitempty"`
	SourceIssue string `json:"source_issue,omitempty"`
	Worker      string `json:"worker,omitempty"`
	Rig         string `json:"rig,omitempty"`
	MergeCommit string `json:"merge_commit,omitempty"`
	CloseReason string `json:"close_reason,omitempty"`

	// Dependencies
	DependsOn []DependencyInfo `json:"depends_on,omitempty"`
	Blocks    []DependencyInfo `json:"blocks,omitempty"`
}

MRStatusOutput is the JSON output structure for gt mq status.

type MoleculeCurrentInfo 

type MoleculeCurrentInfo struct {
	Identity      string `json:"identity"`
	HandoffID     string `json:"handoff_id,omitempty"`
	HandoffTitle  string `json:"handoff_title,omitempty"`
	MoleculeID    string `json:"molecule_id,omitempty"`
	MoleculeTitle string `json:"molecule_title,omitempty"`
	StepsComplete int    `json:"steps_complete"`
	StepsTotal    int    `json:"steps_total"`
	CurrentStepID string `json:"current_step_id,omitempty"`
	CurrentStep   string `json:"current_step,omitempty"`
	Status        string `json:"status"` // "working", "naked", "complete", "blocked"
}

MoleculeCurrentInfo contains info about what an agent should be working on.

type MoleculeCurrentOutput 

type MoleculeCurrentOutput struct {
	MoleculeID    string `json:"molecule_id"`
	MoleculeTitle string `json:"molecule_title"`
	NextStep      *struct {
		ID          string `json:"id"`
		Title       string `json:"title"`
		Description string `json:"description"`
		Status      string `json:"status"`
	} `json:"next_step"`
	Completed int `json:"completed"`
	Total     int `json:"total"`
}

MoleculeCurrentOutput represents the JSON output of bd mol current.

type MoleculeProgressInfo 

type MoleculeProgressInfo struct {
	RootID       string   `json:"root_id"`
	RootTitle    string   `json:"root_title"`
	MoleculeID   string   `json:"molecule_id,omitempty"`
	TotalSteps   int      `json:"total_steps"`
	DoneSteps    int      `json:"done_steps"`
	InProgress   int      `json:"in_progress_steps"`
	ReadySteps   []string `json:"ready_steps"`
	BlockedSteps []string `json:"blocked_steps"`
	Percent      int      `json:"percent_complete"`
	Complete     bool     `json:"complete"`
}

MoleculeProgressInfo contains progress information for a molecule instance.

type MoleculeStatusInfo 

type MoleculeStatusInfo struct {
	Target           string                `json:"target"`
	Role             string                `json:"role"`
	AgentBeadID      string                `json:"agent_bead_id,omitempty"` // The agent bead if found
	HasWork          bool                  `json:"has_work"`
	PinnedBead       *beads.Issue          `json:"pinned_bead,omitempty"`
	AttachedMolecule string                `json:"attached_molecule,omitempty"`
	AttachedAt       string                `json:"attached_at,omitempty"`
	AttachedArgs     string                `json:"attached_args,omitempty"`
	IsWisp           bool                  `json:"is_wisp"`
	Progress         *MoleculeProgressInfo `json:"progress,omitempty"`
	NextAction       string                `json:"next_action,omitempty"`
}

MoleculeStatusInfo contains status information for an agent's work.

type OrphanCommit 

type OrphanCommit struct {
	SHA     string
	Date    time.Time
	Author  string
	Subject string
}

OrphanCommit represents an unreachable commit

type OverseerInfo 

type OverseerInfo struct {
	Name       string `json:"name"`
	Email      string `json:"email,omitempty"`
	Username   string `json:"username,omitempty"`
	Source     string `json:"source"`
	UnreadMail int    `json:"unread_mail"`
}

OverseerInfo represents the human operator's identity and status.

type ParkedWork 

type ParkedWork struct {
	// AgentID is the agent that parked (e.g., "gastown/crew/max")
	AgentID string `json:"agent_id"`

	// GateID is the gate we're parked on
	GateID string `json:"gate_id"`

	// BeadID is the bead/molecule we were working on
	BeadID string `json:"bead_id,omitempty"`

	// Formula is the formula attached to the work (if any)
	Formula string `json:"formula,omitempty"`

	// Context is additional context notes from the agent
	Context string `json:"context,omitempty"`

	// ParkedAt is when the work was parked
	ParkedAt time.Time `json:"parked_at"`
}

ParkedWork represents work state saved when parking on a gate.

type PatrolConfig 

type PatrolConfig struct {
	RoleName        string   // "deacon", "witness", "refinery"
	PatrolMolName   string   // "mol-deacon-patrol", etc.
	BeadsDir        string   // where to look for beads
	Assignee        string   // agent identity for pinning
	HeaderIcon      string   // display icon
	HeaderTitle     string   // "Patrol Status", etc.
	WorkLoopSteps   []string // role-specific instructions
	CheckInProgress bool     // whether to check in_progress status first (witness/refinery do, deacon doesn't)
}

PatrolConfig holds role-specific patrol configuration.

type PolecatListItem 

type PolecatListItem struct {
	Rig            string        `json:"rig"`
	Name           string        `json:"name"`
	State          polecat.State `json:"state"`
	Issue          string        `json:"issue,omitempty"`
	SessionRunning bool          `json:"session_running"`
}

PolecatListItem represents a polecat in list output.

type PolecatStatus 

type PolecatStatus struct {
	Rig            string        `json:"rig"`
	Name           string        `json:"name"`
	State          polecat.State `json:"state"`
	Issue          string        `json:"issue,omitempty"`
	ClonePath      string        `json:"clone_path"`
	Branch         string        `json:"branch"`
	SessionRunning bool          `json:"session_running"`
	SessionID      string        `json:"session_id,omitempty"`
	Attached       bool          `json:"attached,omitempty"`
	Windows        int           `json:"windows,omitempty"`
	CreatedAt      string        `json:"created_at,omitempty"`
	LastActivity   string        `json:"last_activity,omitempty"`
}

PolecatStatus represents detailed polecat status for JSON output.

type RecoveryStatus 

type RecoveryStatus struct {
	Rig           string                `json:"rig"`
	Polecat       string                `json:"polecat"`
	CleanupStatus polecat.CleanupStatus `json:"cleanup_status"`
	NeedsRecovery bool                  `json:"needs_recovery"`
	Verdict       string                `json:"verdict"` // SAFE_TO_NUKE or NEEDS_RECOVERY
	Branch        string                `json:"branch,omitempty"`
	Issue         string                `json:"issue,omitempty"`
}

RecoveryStatus represents whether a polecat needs recovery or is safe to nuke.

type ResumeStatus 

type ResumeStatus struct {
	HasParkedWork bool        `json:"has_parked_work"`
	ParkedWork    *ParkedWork `json:"parked_work,omitempty"`
	GateClosed    bool        `json:"gate_closed"`
	CloseReason   string      `json:"close_reason,omitempty"`
	CanResume     bool        `json:"can_resume"`
}

ResumeStatus represents the current resume state.

type RigStatus 

type RigStatus struct {
	Name         string          `json:"name"`
	Polecats     []string        `json:"polecats"`
	PolecatCount int             `json:"polecat_count"`
	Crews        []string        `json:"crews"`
	CrewCount    int             `json:"crew_count"`
	HasWitness   bool            `json:"has_witness"`
	HasRefinery  bool            `json:"has_refinery"`
	Hooks        []AgentHookInfo `json:"hooks,omitempty"`
	Agents       []AgentRuntime  `json:"agents,omitempty"` // Runtime state of all agents in rig
	MQ           *MQSummary      `json:"mq,omitempty"`     // Merge queue summary
}

RigStatus represents status of a single rig.

type Role 

type Role string

Role represents a detected agent role. 

const (
	RoleMayor    Role = "mayor"
	RoleDeacon   Role = "deacon"
	RoleWitness  Role = "witness"
	RoleRefinery Role = "refinery"
	RolePolecat  Role = "polecat"
	RoleCrew     Role = "crew"
	RoleUnknown  Role = "unknown"
)

type RoleContext 

type RoleContext = RoleInfo

RoleContext is an alias for RoleInfo for backward compatibility. New code should use RoleInfo directly.

type RoleInfo 

type RoleInfo struct {
	Role     Role   `json:"role"`
	Source   string `json:"source"` // "env", "cwd", or "explicit"
	Home     string `json:"home"`
	Rig      string `json:"rig,omitempty"`
	Polecat  string `json:"polecat,omitempty"`
	EnvRole  string `json:"env_role,omitempty"` // Value of GT_ROLE if set
	CwdRole  Role   `json:"cwd_role,omitempty"` // Role detected from cwd
	Mismatch bool   `json:"mismatch,omitempty"` // True if env != cwd detection
	TownRoot string `json:"town_root,omitempty"`
	WorkDir  string `json:"work_dir,omitempty"` // Current working directory
}

RoleInfo contains information about a role and its detection source. This is the canonical struct for role detection - used by both GetRole() and detectRole() functions.

func GetRole 

func GetRole() (RoleInfo, error)

GetRole returns the current role, checking GT_ROLE first then falling back to cwd. This is the canonical function for role detection.

func GetRoleWithContext 

func GetRoleWithContext(cwd, townRoot string) (RoleInfo, error)

GetRoleWithContext returns role info given explicit cwd and town root.

func (RoleInfo) ActorString 

func (info RoleInfo) ActorString() string

ActorString returns the actor identity string for beads attribution. Format matches beads created_by convention:

  • Simple roles: "mayor", "deacon"
  • Rig-specific: "gastown/witness", "gastown/refinery"
  • Workers: "gastown/crew/max", "gastown/polecats/Toast"

type SessionCost 

type SessionCost struct {
	Session string  `json:"session"`
	Role    string  `json:"role"`
	Rig     string  `json:"rig,omitempty"`
	Worker  string  `json:"worker,omitempty"`
	Cost    float64 `json:"cost_usd"`
	Running bool    `json:"running"`
}

SessionCost represents cost info for a single session.

type SessionEvent 

type SessionEvent struct {
	ID        string    `json:"id"`
	Title     string    `json:"title"`
	Status    string    `json:"status"`
	CreatedAt time.Time `json:"created_at"`
	EventKind string    `json:"event_kind"`
	Actor     string    `json:"actor"`
	Target    string    `json:"target"`
	Payload   string    `json:"payload"`
}

SessionEvent represents a session.ended event from beads.

type SessionListItem 

type SessionListItem struct {
	Rig       string `json:"rig"`
	Polecat   string `json:"polecat"`
	SessionID string `json:"session_id"`
	Running   bool   `json:"running"`
}

SessionListItem represents a session in list output.

type SessionPayload 

type SessionPayload struct {
	CostUSD   float64 `json:"cost_usd"`
	SessionID string  `json:"session_id"`
	Role      string  `json:"role"`
	Rig       string  `json:"rig"`
	Worker    string  `json:"worker"`
	EndedAt   string  `json:"ended_at"`
}

SessionPayload represents the JSON payload of a session event.

type SilentExitError 

type SilentExitError struct {
	Code int
}

SilentExitError signals that the command should exit with a specific code without printing an error message. This is used for scripting purposes where exit codes convey status (e.g., "no mail" = exit 1).

func NewSilentExit 

func NewSilentExit(code int) *SilentExitError

NewSilentExit creates a SilentExitError with the given exit code.

func (*SilentExitError) Error 

func (e *SilentExitError) Error() string

type SlingSpawnOptions 

type SlingSpawnOptions struct {
	Force    bool   // Force spawn even if polecat has uncommitted work
	Naked    bool   // No-tmux mode: skip session creation
	Account  string // Claude Code account handle to use
	Create   bool   // Create polecat if it doesn't exist (currently always true for sling)
	HookBead string // Bead ID to set as hook_bead at spawn time (atomic assignment)
	Agent    string // Agent override for this spawn (e.g., "gemini", "codex", "claude-haiku")
}

SlingSpawnOptions contains options for spawning a polecat via sling.

type SpawnedPolecatInfo 

type SpawnedPolecatInfo struct {
	RigName     string // Rig name (e.g., "gastown")
	PolecatName string // Polecat name (e.g., "Toast")
	ClonePath   string // Path to polecat's git worktree
	SessionName string // Tmux session name (e.g., "gt-gastown-p-Toast")
	Pane        string // Tmux pane ID
}

SpawnedPolecatInfo contains info about a spawned polecat session.

func SpawnPolecatForSling 

func SpawnPolecatForSling(rigName string, opts SlingSpawnOptions) (*SpawnedPolecatInfo, error)

SpawnPolecatForSling creates a fresh polecat and optionally starts its session. This is used by gt sling when the target is a rig name. The caller (sling) handles hook attachment and nudging.

func (*SpawnedPolecatInfo) AgentID 

func (s *SpawnedPolecatInfo) AgentID() string

AgentID returns the agent identifier (e.g., "gastown/polecats/Toast")

type StatusSum 

type StatusSum struct {
	RigCount      int `json:"rig_count"`
	PolecatCount  int `json:"polecat_count"`
	CrewCount     int `json:"crew_count"`
	WitnessCount  int `json:"witness_count"`
	RefineryCount int `json:"refinery_count"`
	ActiveHooks   int `json:"active_hooks"`
}

StatusSum provides summary counts.

type StepDoneResult 

type StepDoneResult struct {
	StepID        string `json:"step_id"`
	MoleculeID    string `json:"molecule_id"`
	StepClosed    bool   `json:"step_closed"`
	NextStepID    string `json:"next_step_id,omitempty"`
	NextStepTitle string `json:"next_step_title,omitempty"`
	Complete      bool   `json:"complete"`
	Action        string `json:"action"` // "continue", "done", "no_more_ready"
}

StepDoneResult is the result of a step done operation.

type StopResult 

type StopResult struct {
	Rig       string
	Polecat   string
	SessionID string
	Success   bool
	Error     string
}

StopResult tracks what was stopped.

type TownStatus 

type TownStatus struct {
	Name     string         `json:"name"`
	Location string         `json:"location"`
	Overseer *OverseerInfo  `json:"overseer,omitempty"` // Human operator
	Agents   []AgentRuntime `json:"agents"`             // Global agents (Mayor, Deacon)
	Rigs     []RigStatus    `json:"rigs"`
	Summary  StatusSum      `json:"summary"`
}

TownStatus represents the overall status of the workspace.

type VersionChange 

type VersionChange struct {
	Version string   `json:"version"`
	Date    string   `json:"date"`
	Changes []string `json:"changes"`
}

VersionChange represents agent-relevant changes for a specific version

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.