cmd

package
v0.0.0-...-3e4c954 Latest Latest
Warning

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

 Go to latest Published: Jan 17, 2026 License: MIT Imports: 77 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 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 (
	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 DefaultAgentEmailDomain = "gastown.local"

DefaultAgentEmailDomain is the default domain for agent git emails.

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

HQGitignore is the standard .gitignore for Gas Town HQs

View Source 
const MinBeadsVersion = "0.44.0"

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

View Source 
const PreCheckoutHookScript = `` /* 1359-byte string literal not displayed */

PreCheckoutHookScript is the git pre-checkout hook that prevents accidental branch switches in the town root. The town root should always stay on main.

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.3.1"
	// 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.EmojiMayor,
	AgentDeacon:   constants.EmojiDeacon,
	AgentWitness:  constants.EmojiWitness,
	AgentRefinery: constants.EmojiRefinery,
	AgentCrew:     constants.EmojiCrew,
	AgentPolecat:  constants.EmojiPolecat,
}

AgentTypeIcons maps agent types to display icons. Uses centralized emojis 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. The check is performed only once per process execution.

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 InstallPreCheckoutHook 

func InstallPreCheckoutHook(hqRoot string) error

InstallPreCheckoutHook installs the pre-checkout hook in the town root. This prevents accidental branch switches that can break gt commands.

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 IsPreCheckoutHookInstalled 

func IsPreCheckoutHookInstalled(hqRoot string) bool

IsPreCheckoutHookInstalled checks if the Gas Town pre-checkout hook is installed.

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. Uses errors.As to properly handle wrapped errors. 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 BeadEntry 

type BeadEntry struct {
	ID        string    `json:"id"`
	Title     string    `json:"title"`
	Status    string    `json:"status"`
	Agent     string    `json:"agent,omitempty"`
	UpdatedAt time.Time `json:"updated_at"`
	UpdateRel string    `json:"updated_relative"`
}

BeadEntry represents a bead for output.

type CVSummary 

type CVSummary struct {
	Identity         string           `json:"identity"`
	Created          string           `json:"created,omitempty"`
	Sessions         int              `json:"sessions"`
	IssuesCompleted  int              `json:"issues_completed"`
	IssuesFailed     int              `json:"issues_failed"`
	IssuesAbandoned  int              `json:"issues_abandoned"`
	Languages        map[string]int   `json:"languages,omitempty"`
	WorkTypes        map[string]int   `json:"work_types,omitempty"`
	AvgCompletionMin int              `json:"avg_completion_minutes,omitempty"`
	FirstPassRate    float64          `json:"first_pass_rate,omitempty"`
	RecentWork       []RecentWorkItem `json:"recent_work,omitempty"`
}

CVSummary represents the CV/work history summary for a polecat.

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 CommitEntry 

type CommitEntry struct {
	Hash      string    `json:"hash"`
	ShortHash string    `json:"short_hash"`
	Author    string    `json:"author"`
	Email     string    `json:"email"`
	Date      time.Time `json:"date"`
	DateRel   string    `json:"date_relative"`
	Subject   string    `json:"subject"`
	IsAgent   bool      `json:"is_agent"`
}

CommitEntry represents a git commit for output.

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 CostDigest 

type CostDigest struct {
	Date         string             `json:"date"`
	TotalUSD     float64            `json:"total_usd"`
	SessionCount int                `json:"session_count"`
	Sessions     []CostEntry        `json:"sessions"`
	ByRole       map[string]float64 `json:"by_role"`
	ByRig        map[string]float64 `json:"by_rig,omitempty"`
}

CostDigest represents the aggregated daily cost report.

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 IdentityDetails 

type IdentityDetails struct {
	IdentityInfo
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	CreatedAt   string   `json:"created_at,omitempty"`
	UpdatedAt   string   `json:"updated_at,omitempty"`
	CVBeads     []string `json:"cv_beads,omitempty"`
}

IdentityDetails holds detailed identity information for show command.

type IdentityInfo 

type IdentityInfo struct {
	Rig            string `json:"rig"`
	Name           string `json:"name"`
	BeadID         string `json:"bead_id"`
	AgentState     string `json:"agent_state,omitempty"`
	HookBead       string `json:"hook_bead,omitempty"`
	CleanupStatus  string `json:"cleanup_status,omitempty"`
	WorktreeExists bool   `json:"worktree_exists"`
	SessionRunning bool   `json:"session_running"`
}

IdentityInfo holds identity bead information for display.

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 IssueInfo 

type IssueInfo struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	Type    string `json:"issue_type"`
	Status  string `json:"status"`
	Updated string `json:"updated_at"`
}

IssueInfo holds basic issue information for CV queries.

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 OrphanProcess 

type OrphanProcess struct {
	PID  int
	Args string
}

OrphanProcess represents a Claude process that has become orphaned (PPID=1)

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
	HeaderEmoji     string   // display emoji
	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 PatrolCycleEntry 

type PatrolCycleEntry struct {
	ID          string    `json:"id"`
	Role        string    `json:"role"` // deacon, witness, refinery
	Title       string    `json:"title"`
	Description string    `json:"description"`
	CreatedAt   time.Time `json:"created_at"`
	ClosedAt    time.Time `json:"closed_at,omitempty"`
}

PatrolCycleEntry represents a single patrol cycle in the digest.

type PatrolDigest 

type PatrolDigest struct {
	Date        string             `json:"date"`
	TotalCycles int                `json:"total_cycles"`
	ByRole      map[string]int     `json:"by_role"` // deacon, witness, refinery
	Cycles      []PatrolCycleEntry `json:"cycles"`
}

PatrolDigest represents the aggregated daily patrol report.

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 ReadyResult 

type ReadyResult struct {
	Sources  []ReadySource `json:"sources"`
	Summary  ReadySummary  `json:"summary"`
	TownRoot string        `json:"town_root,omitempty"`
}

ReadyResult is the aggregated result of gt ready.

type ReadySource 

type ReadySource struct {
	Name   string         `json:"name"`   // "town" or rig name
	Issues []*beads.Issue `json:"issues"` // Ready issues from this source
	Error  string         `json:"error,omitempty"`
}

ReadySource represents ready items from a single source (town or rig).

type ReadySummary 

type ReadySummary struct {
	Total    int            `json:"total"`
	BySource map[string]int `json:"by_source"`
	P0Count  int            `json:"p0_count"`
	P1Count  int            `json:"p1_count"`
	P2Count  int            `json:"p2_count"`
	P3Count  int            `json:"p3_count"`
	P4Count  int            `json:"p4_count"`
}

ReadySummary provides counts for the ready report.

type RecentWorkItem 

type RecentWorkItem struct {
	ID        string `json:"id"`
	Title     string `json:"title"`
	Type      string `json:"type,omitempty"`
	Completed string `json:"completed"`
	Ago       string `json:"ago"`
}

RecentWorkItem represents a recent work item in the CV.

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"
	RoleBoot     Role = "boot"
	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
	EnvIncomplete bool   `json:"env_incomplete,omitempty"` // True if env was set but missing rig/polecat, filled from cwd
	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 SafetyCheckResult 

type SafetyCheckResult struct {
	Polecat       string
	Blocked       bool
	Reasons       []string
	CleanupStatus polecat.CleanupStatus
	HookBead      string
	HookStale     bool // true if hooked bead is closed
	OpenMR        string
	GitState      *GitState
}

SafetyCheckResult holds the result of safety checks for a polecat.

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 SessionState 

type SessionState struct {
	State         string `json:"state"`                    // normal, post-handoff, crash-recovery, autonomous
	Role          Role   `json:"role"`                     // detected role
	PrevSession   string `json:"prev_session,omitempty"`   // for post-handoff
	CheckpointAge string `json:"checkpoint_age,omitempty"` // for crash-recovery
	HookedBead    string `json:"hooked_bead,omitempty"`    // for autonomous
}

SessionState represents the detected session state for observability.

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
	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 StaleOutput 

type StaleOutput struct {
	Stale         bool   `json:"stale"`
	BinaryCommit  string `json:"binary_commit"`
	RepoCommit    string `json:"repo_commit"`
	CommitsBehind int    `json:"commits_behind,omitempty"`
	Error         string `json:"error,omitempty"`
}

StaleOutput represents the JSON output structure.

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 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

type WispItem 

type WispItem struct {
	ID        string    `json:"id"`
	Title     string    `json:"title"`
	Status    string    `json:"status"`
	CreatedAt time.Time `json:"created_at"`
}

WispItem represents a single wisp from bd mol wisp list.

type WispListOutput 

type WispListOutput struct {
	Wisps []WispItem `json:"wisps"`
	Count int        `json:"count"`
}

WispListOutput represents the JSON output from bd mol wisp list.

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.