doctor

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jan 22, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package doctor provides a framework for running health checks on Gas Town workspaces.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrCannotFix is returned when a check does not support auto-fix.
	ErrCannotFix = errors.New("check does not support auto-fix")
)

Common errors

Functions

This section is empty.

Types

type AgentBeadsCheck 

type AgentBeadsCheck struct {
	FixableCheck
}

AgentBeadsCheck verifies that agent beads exist for all agents. This includes: - Global agents (deacon, mayor) - stored in town beads with hq- prefix - Per-rig agents (witness, refinery) - stored in each rig's beads - Crew workers - stored in each rig's beads

Agent beads are created by gt rig add (see gt-h3hak, gt-pinkq) and gt crew add. Each rig uses its configured prefix (e.g., "gt-" for gastown, "bd-" for beads).

func NewAgentBeadsCheck 

func NewAgentBeadsCheck() *AgentBeadsCheck

NewAgentBeadsCheck creates a new agent beads check.

func (*AgentBeadsCheck) Fix 

func (c *AgentBeadsCheck) Fix(ctx *CheckContext) error

Fix creates missing agent beads.

func (*AgentBeadsCheck) Run 

func (c *AgentBeadsCheck) Run(ctx *CheckContext) *CheckResult

Run checks if agent beads exist for all expected agents.

type BaseCheck 

type BaseCheck struct {
	CheckName        string
	CheckDescription string
}

BaseCheck provides a base implementation for checks that don't support auto-fix. Embed this in custom checks to get default CanFix() and Fix() implementations.

func (*BaseCheck) CanFix 

func (b *BaseCheck) CanFix() bool

CanFix returns false by default.

func (*BaseCheck) Description 

func (b *BaseCheck) Description() string

Description returns the check description.

func (*BaseCheck) Fix 

func (b *BaseCheck) Fix(ctx *CheckContext) error

Fix returns an error indicating this check cannot be auto-fixed.

func (*BaseCheck) Name 

func (b *BaseCheck) Name() string

Name returns the check name.

type BdDaemonCheck 

type BdDaemonCheck struct {
	FixableCheck
}

BdDaemonCheck verifies that the bd (beads) daemon is running and healthy. When the daemon fails to start, it surfaces the actual error (e.g., legacy database detected, repo mismatch) and provides actionable fix commands.

func NewBdDaemonCheck 

func NewBdDaemonCheck() *BdDaemonCheck

NewBdDaemonCheck creates a new bd daemon check.

func (*BdDaemonCheck) Fix 

func (c *BdDaemonCheck) Fix(ctx *CheckContext) error

Fix attempts to start the bd daemon.

func (*BdDaemonCheck) Run 

func (c *BdDaemonCheck) Run(ctx *CheckContext) *CheckResult

Run checks if the bd daemon is running and healthy.

type BeadsConfigValidCheck 

type BeadsConfigValidCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

BeadsConfigValidCheck verifies beads configuration if .beads/ exists.

func NewBeadsConfigValidCheck 

func NewBeadsConfigValidCheck() *BeadsConfigValidCheck

NewBeadsConfigValidCheck creates a new beads config check.

func (*BeadsConfigValidCheck) Fix 

func (c *BeadsConfigValidCheck) Fix(ctx *CheckContext) error

Fix runs bd sync if needed.

func (*BeadsConfigValidCheck) Run 

func (c *BeadsConfigValidCheck) Run(ctx *CheckContext) *CheckResult

Run checks if beads is properly configured.

type BeadsDatabaseCheck 

type BeadsDatabaseCheck struct {
	FixableCheck
}

BeadsDatabaseCheck verifies that the beads database is properly initialized. It detects when issues.db is empty or missing critical columns, and can auto-fix by triggering a re-import from the JSONL file.

func NewBeadsDatabaseCheck 

func NewBeadsDatabaseCheck() *BeadsDatabaseCheck

NewBeadsDatabaseCheck creates a new beads database check.

func (*BeadsDatabaseCheck) Fix 

func (c *BeadsDatabaseCheck) Fix(ctx *CheckContext) error

Fix attempts to rebuild the database from JSONL.

func (*BeadsDatabaseCheck) Run 

func (c *BeadsDatabaseCheck) Run(ctx *CheckContext) *CheckResult

Run checks if the beads database is properly initialized.

type BeadsRedirectCheck 

type BeadsRedirectCheck struct {
	FixableCheck
}

BeadsRedirectCheck verifies that rig-level beads redirect exists for tracked beads. When a repo has .beads/ tracked in git (at mayor/rig/.beads), the rig root needs a redirect file pointing to that location.

func NewBeadsRedirectCheck 

func NewBeadsRedirectCheck() *BeadsRedirectCheck

NewBeadsRedirectCheck creates a new beads redirect check.

func (*BeadsRedirectCheck) Fix 

func (c *BeadsRedirectCheck) Fix(ctx *CheckContext) error

Fix creates or corrects the rig-level beads redirect, or initializes beads if missing.

func (*BeadsRedirectCheck) Run 

func (c *BeadsRedirectCheck) Run(ctx *CheckContext) *CheckResult

Run checks if the rig-level beads redirect exists when needed.

type BeadsSyncOrphanCheck 

type BeadsSyncOrphanCheck struct {
	BaseCheck
}

BeadsSyncOrphanCheck detects code changes on beads-sync branch that weren't merged to main. This catches cases where merges lose code changes.

func NewBeadsSyncOrphanCheck 

func NewBeadsSyncOrphanCheck() *BeadsSyncOrphanCheck

NewBeadsSyncOrphanCheck creates a new beads-sync orphan check.

func (*BeadsSyncOrphanCheck) Run 

func (c *BeadsSyncOrphanCheck) Run(ctx *CheckContext) *CheckResult

Run checks for code differences between main and beads-sync.

type BootHealthCheck 

type BootHealthCheck struct {
	BaseCheck
}

BootHealthCheck verifies Boot watchdog health. "The vet checks on the dog."

func NewBootHealthCheck 

func NewBootHealthCheck() *BootHealthCheck

NewBootHealthCheck creates a new Boot health check.

func (*BootHealthCheck) Run 

func (c *BootHealthCheck) Run(ctx *CheckContext) *CheckResult

Run checks Boot health: directory, session, status, and marker freshness.

type BranchCheck 

type BranchCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

BranchCheck detects persistent roles (crew, witness, refinery) that are not on the expected branch. The expected branch is read from the rig's config.json default_branch field, falling back to "main".

func NewBranchCheck 

func NewBranchCheck() *BranchCheck

NewBranchCheck creates a new branch check.

func (*BranchCheck) Fix 

func (c *BranchCheck) Fix(ctx *CheckContext) error

Fix switches all off-branch directories to their expected branch.

func (*BranchCheck) Run 

func (c *BranchCheck) Run(ctx *CheckContext) *CheckResult

Run checks if persistent role directories are on the expected branch.

type Check 

type Check interface {
	// Name returns the check identifier.
	Name() string

	// Description returns a human-readable description.
	Description() string

	// Run executes the check and returns a result.
	Run(ctx *CheckContext) *CheckResult

	// Fix attempts to automatically fix the issue.
	// Should only be called if CanFix() returns true.
	Fix(ctx *CheckContext) error

	// CanFix returns true if this check can automatically fix issues.
	CanFix() bool
}

Check defines the interface for a health check.

func RigChecks 

func RigChecks() []Check

RigChecks returns all rig-level health checks.

func WorkspaceChecks 

func WorkspaceChecks() []Check

WorkspaceChecks returns all workspace-level health checks.

type CheckContext 

type CheckContext struct {
	TownRoot        string // Root directory of the Gas Town workspace
	RigName         string // Rig name (empty for town-level checks)
	Verbose         bool   // Enable verbose output
	RestartSessions bool   // Restart patrol sessions when fixing (requires explicit --restart-sessions flag)
}

CheckContext provides context for running checks.

func (*CheckContext) RigPath 

func (ctx *CheckContext) RigPath() string

RigPath returns the full path to the rig directory. Returns empty string if RigName is not set.

type CheckResult 

type CheckResult struct {
	Name    string      // Check name
	Status  CheckStatus // Result status
	Message string      // Primary result message
	Details []string    // Additional information
	FixHint string      // Suggestion if not auto-fixable
}

CheckResult represents the outcome of a health check.

type CheckStatus 

type CheckStatus int

CheckStatus represents the result status of a health check. 

const (
	// StatusOK indicates the check passed.
	StatusOK CheckStatus = iota
	// StatusWarning indicates a non-critical issue.
	StatusWarning
	// StatusError indicates a critical problem.
	StatusError
)

func (CheckStatus) String 

func (s CheckStatus) String() string

String returns a human-readable status.

type CloneDivergenceCheck 

type CloneDivergenceCheck struct {
	BaseCheck
}

CloneDivergenceCheck detects when git clones have drifted significantly apart. This is an emergency condition - all clones should be tracking origin/main and staying reasonably in sync. Divergence here is different from beads-sync divergence, which is expected.

func NewCloneDivergenceCheck 

func NewCloneDivergenceCheck() *CloneDivergenceCheck

NewCloneDivergenceCheck creates a new clone divergence check.

func (*CloneDivergenceCheck) Run 

func (c *CloneDivergenceCheck) Run(ctx *CheckContext) *CheckResult

Run checks for significant divergence between clones.

type CommandsCheck 

type CommandsCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

CommandsCheck validates that town-level .cursor/commands/ is provisioned. All agents inherit these via Cursor's directory traversal - no per-workspace copies needed.

func NewCommandsCheck 

func NewCommandsCheck() *CommandsCheck

NewCommandsCheck creates a new commands check.

func (*CommandsCheck) Fix 

func (c *CommandsCheck) Fix(ctx *CheckContext) error

Fix provisions missing slash commands at town level.

func (*CommandsCheck) Run 

func (c *CommandsCheck) Run(ctx *CheckContext) *CheckResult

Run checks if town-level slash commands are provisioned.

type CrewStateCheck 

type CrewStateCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

CrewStateCheck validates crew worker state.json files for completeness. Empty or incomplete state.json files cause "can't find pane/session" errors.

func NewCrewStateCheck 

func NewCrewStateCheck() *CrewStateCheck

NewCrewStateCheck creates a new crew state check.

func (*CrewStateCheck) Fix 

func (c *CrewStateCheck) Fix(ctx *CheckContext) error

Fix regenerates invalid state.json files with correct values.

func (*CrewStateCheck) Run 

func (c *CrewStateCheck) Run(ctx *CheckContext) *CheckResult

Run checks all crew state.json files for completeness.

type CrewWorktreeCheck 

type CrewWorktreeCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

CrewWorktreeCheck detects stale cross-rig worktrees in crew directories. Cross-rig worktrees are created by `gt worktree <rig>` and live in crew/ with names like `<source-rig>-<crewname>`. They should be cleaned up when no longer needed to avoid confusion with regular crew workspaces.

func NewCrewWorktreeCheck 

func NewCrewWorktreeCheck() *CrewWorktreeCheck

NewCrewWorktreeCheck creates a new crew worktree check.

func (*CrewWorktreeCheck) Fix 

func (c *CrewWorktreeCheck) Fix(ctx *CheckContext) error

Fix removes stale cross-rig worktrees.

func (*CrewWorktreeCheck) Run 

func (c *CrewWorktreeCheck) Run(ctx *CheckContext) *CheckResult

Run checks for cross-rig worktrees that may need cleanup.

type CursorSettingsCheck 

type CursorSettingsCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

CursorSettingsCheck verifies that Cursor settings files match the expected templates. Detects stale settings files that are missing required hooks or configuration.

func NewCursorSettingsCheck 

func NewCursorSettingsCheck() *CursorSettingsCheck

NewCursorSettingsCheck creates a new Cursor settings validation check.

func (*CursorSettingsCheck) Fix 

func (c *CursorSettingsCheck) Fix(ctx *CheckContext) error

Fix deletes stale settings files and restarts affected agents. Files with local modifications are skipped to avoid losing user changes.

func (*CursorSettingsCheck) Run 

func (c *CursorSettingsCheck) Run(ctx *CheckContext) *CheckResult

Run checks all Cursor settings files for staleness.

type DaemonCheck 

type DaemonCheck struct {
	FixableCheck
}

DaemonCheck verifies the daemon is running.

func NewDaemonCheck 

func NewDaemonCheck() *DaemonCheck

NewDaemonCheck creates a new daemon check.

func (*DaemonCheck) Fix 

func (c *DaemonCheck) Fix(ctx *CheckContext) error

Fix starts the daemon.

func (*DaemonCheck) Run 

func (c *DaemonCheck) Run(ctx *CheckContext) *CheckResult

Run checks if the daemon is running.

type Doctor 

type Doctor struct {
	// contains filtered or unexported fields
}

Doctor manages and executes health checks.

func NewDoctor 

func NewDoctor() *Doctor

NewDoctor creates a new Doctor with no registered checks.

func (*Doctor) Checks 

func (d *Doctor) Checks() []Check

Checks returns the list of registered checks.

func (*Doctor) Fix 

func (d *Doctor) Fix(ctx *CheckContext) *Report

Fix runs all checks with auto-fix enabled where possible. It first runs the check, then if it fails and can be fixed, attempts the fix.

func (*Doctor) Register 

func (d *Doctor) Register(check Check)

Register adds a check to the doctor's check list.

func (*Doctor) RegisterAll 

func (d *Doctor) RegisterAll(checks ...Check)

RegisterAll adds multiple checks to the doctor's check list.

func (*Doctor) Run 

func (d *Doctor) Run(ctx *CheckContext) *Report

Run executes all registered checks and returns a report.

type FixableCheck 

type FixableCheck struct {
	BaseCheck
}

FixableCheck provides a base implementation for checks that support auto-fix. Embed this and override CanFix() to return true, and implement Fix().

func (*FixableCheck) CanFix 

func (f *FixableCheck) CanFix() bool

CanFix returns true for fixable checks.

type GitExcludeConfiguredCheck 

type GitExcludeConfiguredCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

GitExcludeConfiguredCheck verifies .git/info/exclude has Gas Town directories.

func NewGitExcludeConfiguredCheck 

func NewGitExcludeConfiguredCheck() *GitExcludeConfiguredCheck

NewGitExcludeConfiguredCheck creates a new git exclude check.

func (*GitExcludeConfiguredCheck) Fix 

func (c *GitExcludeConfiguredCheck) Fix(ctx *CheckContext) error

Fix appends missing entries to .git/info/exclude.

func (*GitExcludeConfiguredCheck) Run 

func (c *GitExcludeConfiguredCheck) Run(ctx *CheckContext) *CheckResult

Run checks if .git/info/exclude contains required entries.

type HookAttachmentValidCheck 

type HookAttachmentValidCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

HookAttachmentValidCheck verifies that attached molecules exist and are not closed. This detects when a hook's attached_molecule field points to a non-existent or closed issue, which can leave agents with stale work assignments.

func NewHookAttachmentValidCheck 

func NewHookAttachmentValidCheck() *HookAttachmentValidCheck

NewHookAttachmentValidCheck creates a new hook attachment validation check.

func (*HookAttachmentValidCheck) Fix 

func (c *HookAttachmentValidCheck) Fix(ctx *CheckContext) error

Fix detaches all invalid molecule attachments.

func (*HookAttachmentValidCheck) Run 

func (c *HookAttachmentValidCheck) Run(ctx *CheckContext) *CheckResult

Run checks all pinned beads for invalid molecule attachments.

type HookSingletonCheck 

type HookSingletonCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

HookSingletonCheck ensures each agent has at most one handoff bead. Detects when multiple pinned beads exist with the same "{role} Handoff" title, which can cause confusion about which handoff is authoritative.

func NewHookSingletonCheck 

func NewHookSingletonCheck() *HookSingletonCheck

NewHookSingletonCheck creates a new hook singleton check.

func (*HookSingletonCheck) Fix 

func (c *HookSingletonCheck) Fix(ctx *CheckContext) error

Fix closes duplicate handoff beads, keeping the first one.

func (*HookSingletonCheck) Run 

func (c *HookSingletonCheck) Run(ctx *CheckContext) *CheckResult

Run checks all pinned beads for duplicate handoff titles.

type HooksPathConfiguredCheck 

type HooksPathConfiguredCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

HooksPathConfiguredCheck verifies all clones have core.hooksPath set to .githooks. This ensures the pre-push hook blocks pushes to invalid branches (no internal PRs).

func NewHooksPathConfiguredCheck 

func NewHooksPathConfiguredCheck() *HooksPathConfiguredCheck

NewHooksPathConfiguredCheck creates a new hooks path check.

func (*HooksPathConfiguredCheck) Fix 

func (c *HooksPathConfiguredCheck) Fix(ctx *CheckContext) error

Fix configures core.hooksPath for all unconfigured clones.

func (*HooksPathConfiguredCheck) Run 

func (c *HooksPathConfiguredCheck) Run(ctx *CheckContext) *CheckResult

Run checks if all clones have core.hooksPath configured.

type IdentityCollisionCheck 

type IdentityCollisionCheck struct{}

IdentityCollisionCheck checks for agent identity collisions and stale locks.

func NewIdentityCollisionCheck 

func NewIdentityCollisionCheck() *IdentityCollisionCheck

NewIdentityCollisionCheck creates a new identity collision check.

func (*IdentityCollisionCheck) CanFix 

func (c *IdentityCollisionCheck) CanFix() bool

func (*IdentityCollisionCheck) Description 

func (c *IdentityCollisionCheck) Description() string

func (*IdentityCollisionCheck) Fix 

func (c *IdentityCollisionCheck) Fix(ctx *CheckContext) error

func (*IdentityCollisionCheck) Name 

func (c *IdentityCollisionCheck) Name() string

func (*IdentityCollisionCheck) Run 

func (c *IdentityCollisionCheck) Run(ctx *CheckContext) *CheckResult

type LegacyGastownCheck 

type LegacyGastownCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

LegacyGastownCheck warns if old .gastown/ directories still exist.

func NewLegacyGastownCheck 

func NewLegacyGastownCheck() *LegacyGastownCheck

NewLegacyGastownCheck creates a new legacy gastown check.

func (*LegacyGastownCheck) Fix 

func (c *LegacyGastownCheck) Fix(ctx *CheckContext) error

Fix removes legacy .gastown/ directories.

func (*LegacyGastownCheck) Run 

func (c *LegacyGastownCheck) Run(ctx *CheckContext) *CheckResult

Run checks for legacy .gastown/ directories.

type LifecycleHygieneCheck 

type LifecycleHygieneCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

LifecycleHygieneCheck detects and cleans up stale lifecycle state. This can happen when lifecycle messages weren't properly deleted after processing.

func NewLifecycleHygieneCheck 

func NewLifecycleHygieneCheck() *LifecycleHygieneCheck

NewLifecycleHygieneCheck creates a new lifecycle hygiene check.

func (*LifecycleHygieneCheck) Fix 

func (c *LifecycleHygieneCheck) Fix(ctx *CheckContext) error

Fix cleans up stale lifecycle messages.

func (*LifecycleHygieneCheck) Run 

func (c *LifecycleHygieneCheck) Run(ctx *CheckContext) *CheckResult

Run checks for stale lifecycle state.

type LinkedPaneCheck 

type LinkedPaneCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

LinkedPaneCheck detects tmux sessions that share panes, which can cause crosstalk (messages sent to one session appearing in another).

func NewLinkedPaneCheck 

func NewLinkedPaneCheck() *LinkedPaneCheck

NewLinkedPaneCheck creates a new linked pane check.

func (*LinkedPaneCheck) Fix 

func (c *LinkedPaneCheck) Fix(ctx *CheckContext) error

Fix kills sessions with linked panes (except mayor session). The daemon will recreate them with independent panes.

func (*LinkedPaneCheck) Run 

func (c *LinkedPaneCheck) Run(ctx *CheckContext) *CheckResult

Run checks for linked panes across Gas Town tmux sessions.

type MayorCloneExistsCheck 

type MayorCloneExistsCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

MayorCloneExistsCheck verifies the mayor/rig clone exists.

func NewMayorCloneExistsCheck 

func NewMayorCloneExistsCheck() *MayorCloneExistsCheck

NewMayorCloneExistsCheck creates a new mayor clone check.

func (*MayorCloneExistsCheck) Fix 

func (c *MayorCloneExistsCheck) Fix(ctx *CheckContext) error

Fix creates missing mayor structure.

func (*MayorCloneExistsCheck) Run 

func (c *MayorCloneExistsCheck) Run(ctx *CheckContext) *CheckResult

Run checks if the mayor/rig clone exists.

type MayorExistsCheck 

type MayorExistsCheck struct {
	BaseCheck
}

MayorExistsCheck verifies the mayor/ directory structure.

func NewMayorExistsCheck 

func NewMayorExistsCheck() *MayorExistsCheck

NewMayorExistsCheck creates a new mayor directory check.

func (*MayorExistsCheck) Run 

func (c *MayorExistsCheck) Run(ctx *CheckContext) *CheckResult

Run checks if mayor/ directory exists with expected contents.

type OrphanProcessCheck 

type OrphanProcessCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

OrphanProcessCheck detects orphaned agent processes that are not associated with a Gas Town tmux session.

func NewOrphanProcessCheck 

func NewOrphanProcessCheck() *OrphanProcessCheck

NewOrphanProcessCheck creates a new orphan process check.

func (*OrphanProcessCheck) Fix 

func (c *OrphanProcessCheck) Fix(ctx *CheckContext) error

Fix kills orphaned processes, with safeguards for crew sessions.

func (*OrphanProcessCheck) Run 

func (c *OrphanProcessCheck) Run(ctx *CheckContext) *CheckResult

Run checks for orphaned agent processes.

type OrphanSessionCheck 

type OrphanSessionCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

OrphanSessionCheck detects orphaned tmux sessions that don't match the expected Gas Town session naming patterns.

func NewOrphanSessionCheck 

func NewOrphanSessionCheck() *OrphanSessionCheck

NewOrphanSessionCheck creates a new orphan session check.

func (*OrphanSessionCheck) Fix 

func (c *OrphanSessionCheck) Fix(ctx *CheckContext) error

Fix kills all orphaned sessions, except crew sessions which are protected.

func (*OrphanSessionCheck) Run 

func (c *OrphanSessionCheck) Run(ctx *CheckContext) *CheckResult

Run checks for orphaned Gas Town tmux sessions.

type OrphanedAttachmentsCheck 

type OrphanedAttachmentsCheck struct {
	BaseCheck
	// contains filtered or unexported fields
}

OrphanedAttachmentsCheck detects handoff beads for agents that no longer exist. This happens when a polecat worktree is deleted but its handoff bead remains, leaving molecules attached to non-existent agents.

func NewOrphanedAttachmentsCheck 

func NewOrphanedAttachmentsCheck() *OrphanedAttachmentsCheck

NewOrphanedAttachmentsCheck creates a new orphaned attachments check.

func (*OrphanedAttachmentsCheck) Run 

func (c *OrphanedAttachmentsCheck) Run(ctx *CheckContext) *CheckResult

Run checks all handoff beads for orphaned agents.

type PatrolHooksWiredCheck 

type PatrolHooksWiredCheck struct {
	FixableCheck
}

PatrolHooksWiredCheck verifies that hooks trigger patrol execution.

func NewPatrolHooksWiredCheck 

func NewPatrolHooksWiredCheck() *PatrolHooksWiredCheck

NewPatrolHooksWiredCheck creates a new patrol hooks wired check.

func (*PatrolHooksWiredCheck) Fix 

func (c *PatrolHooksWiredCheck) Fix(ctx *CheckContext) error

Fix creates the daemon patrol config with defaults.

func (*PatrolHooksWiredCheck) Run 

func (c *PatrolHooksWiredCheck) Run(ctx *CheckContext) *CheckResult

Run checks if patrol hooks are wired.

type PatrolMoleculesExistCheck 

type PatrolMoleculesExistCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

PatrolMoleculesExistCheck verifies that patrol molecules exist for each rig.

func NewPatrolMoleculesExistCheck 

func NewPatrolMoleculesExistCheck() *PatrolMoleculesExistCheck

NewPatrolMoleculesExistCheck creates a new patrol molecules exist check.

func (*PatrolMoleculesExistCheck) Fix 

func (c *PatrolMoleculesExistCheck) Fix(ctx *CheckContext) error

Fix creates missing patrol molecules.

func (*PatrolMoleculesExistCheck) Run 

func (c *PatrolMoleculesExistCheck) Run(ctx *CheckContext) *CheckResult

Run checks if patrol molecules exist.

type PatrolNotStuckCheck 

type PatrolNotStuckCheck struct {
	BaseCheck
	// contains filtered or unexported fields
}

PatrolNotStuckCheck detects wisps that have been in_progress too long.

func NewPatrolNotStuckCheck 

func NewPatrolNotStuckCheck() *PatrolNotStuckCheck

NewPatrolNotStuckCheck creates a new patrol not stuck check.

func (*PatrolNotStuckCheck) Run 

func (c *PatrolNotStuckCheck) Run(ctx *CheckContext) *CheckResult

Run checks for stuck patrol wisps.

type PatrolPluginsAccessibleCheck 

type PatrolPluginsAccessibleCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

PatrolPluginsAccessibleCheck verifies plugin directories exist and are readable.

func NewPatrolPluginsAccessibleCheck 

func NewPatrolPluginsAccessibleCheck() *PatrolPluginsAccessibleCheck

NewPatrolPluginsAccessibleCheck creates a new patrol plugins accessible check.

func (*PatrolPluginsAccessibleCheck) Fix 

func (c *PatrolPluginsAccessibleCheck) Fix(ctx *CheckContext) error

Fix creates missing plugin directories.

func (*PatrolPluginsAccessibleCheck) Run 

func (c *PatrolPluginsAccessibleCheck) Run(ctx *CheckContext) *CheckResult

Run checks if plugin directories are accessible.

type PatrolRolesHavePromptsCheck 

type PatrolRolesHavePromptsCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

PatrolRolesHavePromptsCheck verifies that internal/templates/roles/*.md.tmpl exist for each rig. Checks at <town>/<rig>/mayor/rig/internal/templates/roles/*.md.tmpl Fix copies embedded templates to missing locations.

func NewPatrolRolesHavePromptsCheck 

func NewPatrolRolesHavePromptsCheck() *PatrolRolesHavePromptsCheck

NewPatrolRolesHavePromptsCheck creates a new patrol roles have prompts check.

func (*PatrolRolesHavePromptsCheck) Fix 

func (c *PatrolRolesHavePromptsCheck) Fix(ctx *CheckContext) error

func (*PatrolRolesHavePromptsCheck) Run 

func (c *PatrolRolesHavePromptsCheck) Run(ctx *CheckContext) *CheckResult

type PolecatClonesValidCheck 

type PolecatClonesValidCheck struct {
	BaseCheck
}

PolecatClonesValidCheck verifies each polecat directory is a valid clone.

func NewPolecatClonesValidCheck 

func NewPolecatClonesValidCheck() *PolecatClonesValidCheck

NewPolecatClonesValidCheck creates a new polecat clones check.

func (*PolecatClonesValidCheck) Run 

func (c *PolecatClonesValidCheck) Run(ctx *CheckContext) *CheckResult

Run checks if each polecat directory is a valid git clone.

type PrefixConflictCheck 

type PrefixConflictCheck struct {
	BaseCheck
}

PrefixConflictCheck detects duplicate prefixes across rigs in routes.jsonl. Duplicate prefixes break prefix-based routing.

func NewPrefixConflictCheck 

func NewPrefixConflictCheck() *PrefixConflictCheck

NewPrefixConflictCheck creates a new prefix conflict check.

func (*PrefixConflictCheck) Run 

func (c *PrefixConflictCheck) Run(ctx *CheckContext) *CheckResult

Run checks for duplicate prefixes in routes.jsonl.

type PrefixMismatchCheck 

type PrefixMismatchCheck struct {
	FixableCheck
}

PrefixMismatchCheck detects when rigs.json has a different prefix than what routes.jsonl actually uses for a rig. This can happen when: - deriveBeadsPrefix() generates a different prefix than what's in the beads DB - Someone manually edited rigs.json with the wrong prefix - The beads were initialized before auto-derive existed with a different prefix

func NewPrefixMismatchCheck 

func NewPrefixMismatchCheck() *PrefixMismatchCheck

NewPrefixMismatchCheck creates a new prefix mismatch check.

func (*PrefixMismatchCheck) Fix 

func (c *PrefixMismatchCheck) Fix(ctx *CheckContext) error

Fix updates rigs.json to match the prefixes in routes.jsonl.

func (*PrefixMismatchCheck) Run 

func (c *PrefixMismatchCheck) Run(ctx *CheckContext) *CheckResult

Run checks for prefix mismatches between rigs.json and routes.jsonl.

type RefineryExistsCheck 

type RefineryExistsCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

RefineryExistsCheck verifies the refinery directory structure exists.

func NewRefineryExistsCheck 

func NewRefineryExistsCheck() *RefineryExistsCheck

NewRefineryExistsCheck creates a new refinery exists check.

func (*RefineryExistsCheck) Fix 

func (c *RefineryExistsCheck) Fix(ctx *CheckContext) error

Fix creates missing refinery structure.

func (*RefineryExistsCheck) Run 

func (c *RefineryExistsCheck) Run(ctx *CheckContext) *CheckResult

Run checks if the refinery directory structure exists.

type RepoFingerprintCheck 

type RepoFingerprintCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

RepoFingerprintCheck verifies that beads databases have valid repository fingerprints. A missing or mismatched fingerprint can cause daemon startup failures and sync issues.

func NewRepoFingerprintCheck 

func NewRepoFingerprintCheck() *RepoFingerprintCheck

NewRepoFingerprintCheck creates a new repo fingerprint check.

func (*RepoFingerprintCheck) Fix 

func (c *RepoFingerprintCheck) Fix(ctx *CheckContext) error

Fix runs bd migrate --update-repo-id and restarts the daemon.

func (*RepoFingerprintCheck) Run 

func (c *RepoFingerprintCheck) Run(ctx *CheckContext) *CheckResult

Run checks if beads databases have valid repo fingerprints.

type Report 

type Report struct {
	Timestamp time.Time
	Checks    []*CheckResult
	Summary   ReportSummary
}

Report contains all check results and a summary.

func NewReport 

func NewReport() *Report

NewReport creates an empty report with the current timestamp.

func (*Report) Add 

func (r *Report) Add(result *CheckResult)

Add adds a check result to the report and updates the summary.

func (*Report) HasErrors 

func (r *Report) HasErrors() bool

HasErrors returns true if any check reported an error.

func (*Report) HasWarnings 

func (r *Report) HasWarnings() bool

HasWarnings returns true if any check reported a warning.

func (*Report) IsHealthy 

func (r *Report) IsHealthy() bool

IsHealthy returns true if all checks passed without errors or warnings.

func (*Report) Print 

func (r *Report) Print(w io.Writer, verbose bool)

Print outputs the report to the given writer.

type ReportSummary 

type ReportSummary struct {
	Total    int
	OK       int
	Warnings int
	Errors   int
}

ReportSummary summarizes the results of all checks.

type RigIsGitRepoCheck 

type RigIsGitRepoCheck struct {
	BaseCheck
}

RigIsGitRepoCheck verifies the rig has a valid mayor/rig git clone. Note: The rig directory itself is not a git repo - it contains clones.

func NewRigIsGitRepoCheck 

func NewRigIsGitRepoCheck() *RigIsGitRepoCheck

NewRigIsGitRepoCheck creates a new rig git repo check.

func (*RigIsGitRepoCheck) Run 

func (c *RigIsGitRepoCheck) Run(ctx *CheckContext) *CheckResult

Run checks if the rig has a valid mayor/rig git clone.

type RigsRegistryExistsCheck 

type RigsRegistryExistsCheck struct {
	FixableCheck
}

RigsRegistryExistsCheck verifies mayor/rigs.json exists.

func NewRigsRegistryExistsCheck 

func NewRigsRegistryExistsCheck() *RigsRegistryExistsCheck

NewRigsRegistryExistsCheck creates a new rigs registry exists check.

func (*RigsRegistryExistsCheck) Fix 

func (c *RigsRegistryExistsCheck) Fix(ctx *CheckContext) error

Fix creates an empty rigs.json file.

func (*RigsRegistryExistsCheck) Run 

func (c *RigsRegistryExistsCheck) Run(ctx *CheckContext) *CheckResult

Run checks if mayor/rigs.json exists.

type RigsRegistryValidCheck 

type RigsRegistryValidCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

RigsRegistryValidCheck verifies mayor/rigs.json is valid and rigs exist.

func NewRigsRegistryValidCheck 

func NewRigsRegistryValidCheck() *RigsRegistryValidCheck

NewRigsRegistryValidCheck creates a new rigs registry validation check.

func (*RigsRegistryValidCheck) Fix 

func (c *RigsRegistryValidCheck) Fix(ctx *CheckContext) error

Fix removes missing rigs from the registry.

func (*RigsRegistryValidCheck) Run 

func (c *RigsRegistryValidCheck) Run(ctx *CheckContext) *CheckResult

Run validates mayor/rigs.json and checks that registered rigs exist.

type RoutesCheck 

type RoutesCheck struct {
	FixableCheck
}

RoutesCheck verifies that beads routing is properly configured. It checks that routes.jsonl exists, all rigs have routing entries, and all routes point to valid locations.

func NewRoutesCheck 

func NewRoutesCheck() *RoutesCheck

NewRoutesCheck creates a new routes configuration check.

func (*RoutesCheck) Fix 

func (c *RoutesCheck) Fix(ctx *CheckContext) error

Fix attempts to add missing routing entries.

func (*RoutesCheck) Run 

func (c *RoutesCheck) Run(ctx *CheckContext) *CheckResult

Run checks the beads routing configuration.

type RuntimeGitignoreCheck 

type RuntimeGitignoreCheck struct {
	BaseCheck
}

RuntimeGitignoreCheck verifies .runtime/ is gitignored at town and rig levels.

func NewRuntimeGitignoreCheck 

func NewRuntimeGitignoreCheck() *RuntimeGitignoreCheck

NewRuntimeGitignoreCheck creates a new runtime gitignore check.

func (*RuntimeGitignoreCheck) Run 

func (c *RuntimeGitignoreCheck) Run(ctx *CheckContext) *CheckResult

Run checks if .runtime/ is properly gitignored.

type SessionHookCheck 

type SessionHookCheck struct {
	BaseCheck
}

SessionHookCheck verifies settings.json files use session-start.sh for proper session_id passthrough. Without this wrapper, gt seance cannot discover sessions.

func NewSessionHookCheck 

func NewSessionHookCheck() *SessionHookCheck

NewSessionHookCheck creates a new session hook check.

func (*SessionHookCheck) Run 

func (c *SessionHookCheck) Run(ctx *CheckContext) *CheckResult

Run checks if all settings.json files use session-start.sh wrapper. NOTE: This check validates Cursor hooks configuration. The .cursor/hooks.json files are skipped since Cursor uses .cursor/ directories with different hooks.

type SettingsCheck 

type SettingsCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

SettingsCheck verifies each rig has a settings/ directory.

func NewSettingsCheck 

func NewSettingsCheck() *SettingsCheck

NewSettingsCheck creates a new settings directory check.

func (*SettingsCheck) Fix 

func (c *SettingsCheck) Fix(ctx *CheckContext) error

Fix creates missing settings/ directories.

func (*SettingsCheck) Run 

func (c *SettingsCheck) Run(ctx *CheckContext) *CheckResult

Run checks if all rigs have a settings/ directory.

type SparseCheckoutCheck 

type SparseCheckoutCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

SparseCheckoutCheck verifies that git clones/worktrees have sparse checkout configured to exclude Cursor context files from source repos. This ensures source repo settings and instructions don't override Gas Town agent configuration. Excluded files: .cursor/, .mcp.json

func NewSparseCheckoutCheck 

func NewSparseCheckoutCheck() *SparseCheckoutCheck

NewSparseCheckoutCheck creates a new sparse checkout check.

func (*SparseCheckoutCheck) Fix 

func (c *SparseCheckoutCheck) Fix(ctx *CheckContext) error

Fix configures sparse checkout for affected repos to exclude Cursor context files.

func (*SparseCheckoutCheck) Run 

func (c *SparseCheckoutCheck) Run(ctx *CheckContext) *CheckResult

Run checks if sparse checkout is configured for all git repos in the rig.

type ThemeCheck 

type ThemeCheck struct {
	FixableCheck
}

ThemeCheck verifies tmux sessions have correct themes applied.

func NewThemeCheck 

func NewThemeCheck() *ThemeCheck

NewThemeCheck creates a new theme check.

func (*ThemeCheck) Fix 

func (c *ThemeCheck) Fix(ctx *CheckContext) error

Fix applies themes to all sessions.

func (*ThemeCheck) Run 

func (c *ThemeCheck) Run(ctx *CheckContext) *CheckResult

Run checks if tmux sessions have themes applied correctly.

type TownConfigExistsCheck 

type TownConfigExistsCheck struct {
	BaseCheck
}

TownConfigExistsCheck verifies mayor/town.json exists.

func NewTownConfigExistsCheck 

func NewTownConfigExistsCheck() *TownConfigExistsCheck

NewTownConfigExistsCheck creates a new town config exists check.

func (*TownConfigExistsCheck) Run 

func (c *TownConfigExistsCheck) Run(ctx *CheckContext) *CheckResult

Run checks if mayor/town.json exists.

type TownConfigValidCheck 

type TownConfigValidCheck struct {
	BaseCheck
}

TownConfigValidCheck verifies mayor/town.json is valid JSON with required fields.

func NewTownConfigValidCheck 

func NewTownConfigValidCheck() *TownConfigValidCheck

NewTownConfigValidCheck creates a new town config validation check.

func (*TownConfigValidCheck) Run 

func (c *TownConfigValidCheck) Run(ctx *CheckContext) *CheckResult

Run validates mayor/town.json contents.

type TownGitCheck 

type TownGitCheck struct {
	BaseCheck
}

TownGitCheck verifies that the town root directory is under version control. Having the town harness in git is optional but recommended for: - Backing up personal Gas Town configuration and operating history - Tracking mail and coordination beads - Easier federation across machines

func NewTownGitCheck 

func NewTownGitCheck() *TownGitCheck

NewTownGitCheck creates a new town git version control check.

func (*TownGitCheck) Run 

func (c *TownGitCheck) Run(ctx *CheckContext) *CheckResult

Run checks if the town root has a .git directory.

type WispGCCheck 

type WispGCCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

WispGCCheck detects and cleans orphaned wisps that are older than a threshold. Wisps are ephemeral issues (Wisp: true flag) used for patrol cycles and operational workflows that shouldn't accumulate.

func NewWispGCCheck 

func NewWispGCCheck() *WispGCCheck

NewWispGCCheck creates a new wisp GC check with 1 hour threshold.

func (*WispGCCheck) Fix 

func (c *WispGCCheck) Fix(ctx *CheckContext) error

Fix runs bd mol wisp gc in each rig with abandoned wisps.

func (*WispGCCheck) Run 

func (c *WispGCCheck) Run(ctx *CheckContext) *CheckResult

Run checks for abandoned wisps in each rig.

type WitnessExistsCheck 

type WitnessExistsCheck struct {
	FixableCheck
	// contains filtered or unexported fields
}

WitnessExistsCheck verifies the witness directory structure exists.

func NewWitnessExistsCheck 

func NewWitnessExistsCheck() *WitnessExistsCheck

NewWitnessExistsCheck creates a new witness exists check.

func (*WitnessExistsCheck) Fix 

func (c *WitnessExistsCheck) Fix(ctx *CheckContext) error

Fix creates missing witness structure.

func (*WitnessExistsCheck) Run 

func (c *WitnessExistsCheck) Run(ctx *CheckContext) *CheckResult

Run checks if the witness directory structure exists.

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.