diff --git a/README.md b/README.md index e9e39ed1..b1c124ec 100644 --- a/README.md +++ b/README.md @@ -316,7 +316,7 @@ gt sling # Assign work to agent gt sling --agent cursor # Override runtime for this sling/spawn gt mayor attach # Start Mayor session gt mayor start --agent auggie # Run Mayor with a specific agent alias -gt prime # Alternative to mayor attach +gt prime # Context recovery (run inside existing session) ``` **Built-in agent presets**: `claude`, `gemini`, `codex`, `cursor`, `auggie`, `amp` diff --git a/internal/activity/activity.go b/internal/activity/activity.go index 9a4cfd66..80c45e43 100644 --- a/internal/activity/activity.go +++ b/internal/activity/activity.go @@ -92,6 +92,10 @@ func formatDays(d time.Duration) string { return formatInt(days) + "d" } +// formatInt converts a non-negative integer to its decimal string representation. +// For single digits (0-9), it uses direct rune conversion for efficiency. +// For larger numbers, it extracts digits iteratively from least to most significant. +// This avoids importing strconv for simple integer formatting in the activity package. func formatInt(n int) string { if n < 10 { return string(rune('0'+n)) diff --git a/internal/keepalive/keepalive.go b/internal/keepalive/keepalive.go index 69d79716..9a1137cf 100644 --- a/internal/keepalive/keepalive.go +++ b/internal/keepalive/keepalive.go @@ -10,6 +10,26 @@ // Functions in this package write JSON files to .runtime/ or daemon/ directories. // These files are used by the daemon to detect agent activity and implement // features like exponential backoff during idle periods. +// +// # Sentinel Pattern +// +// This package uses the nil sentinel pattern for graceful degradation: +// +// - [Read] returns nil when the keepalive file doesn't exist or can't be parsed, +// rather than returning an error. This allows callers to treat "no signal" +// and "stale signal" uniformly. +// +// - [State.Age] accepts nil receivers and returns a sentinel duration of 365 days, +// which is guaranteed to exceed any reasonable staleness threshold. This enables +// simple threshold checks without nil guards: +// +// state := keepalive.Read(root) +// if state.Age() > 5*time.Minute { +// // Agent is idle or keepalive missing - both handled the same way +// } +// +// The sentinel approach simplifies daemon logic by eliminating error-handling +// branches for the common case of missing or stale keepalives. package keepalive import ( @@ -76,7 +96,10 @@ func TouchInWorkspace(workspaceRoot, command string) { } // Read returns the current keepalive state for the workspace. -// Returns nil if the file doesn't exist or can't be read. +// +// This function uses the nil sentinel pattern: it returns nil (not an error) +// when the keepalive file doesn't exist, can't be read, or contains invalid JSON. +// Callers can safely pass the result to [State.Age] without nil checks. func Read(workspaceRoot string) *State { keepalivePath := filepath.Join(workspaceRoot, ".runtime", "keepalive.json") @@ -94,10 +117,21 @@ func Read(workspaceRoot string) *State { } // Age returns how old the keepalive signal is. -// Returns a very large duration if the state is nil. +// +// This method implements the sentinel pattern by accepting nil receivers. +// When s is nil (indicating no keepalive exists), it returns 365 days—a value +// guaranteed to exceed any reasonable staleness threshold. This allows callers +// to write simple threshold checks without nil guards: +// +// if keepalive.Read(root).Age() > 5*time.Minute { ... } +// +// The 365-day sentinel was chosen because: +// - It exceeds any practical idle timeout (typically seconds to minutes) +// - It's semantically "infinitely old" for activity detection purposes +// - It avoids magic values like MaxInt64 that could cause overflow issues func (s *State) Age() time.Duration { if s == nil { - return 24 * time.Hour * 365 // No keepalive + return 24 * time.Hour * 365 // Sentinel: treat missing keepalive as maximally stale } return time.Since(s.Timestamp) } diff --git a/internal/mq/id.go b/internal/mq/id.go index 3ec021d2..9468d511 100644 --- a/internal/mq/id.go +++ b/internal/mq/id.go @@ -30,6 +30,13 @@ func GenerateMRID(prefix, branch string) string { // GenerateMRIDWithTime generates a merge request ID using a specific timestamp. // This is primarily useful for testing to ensure deterministic output. // Note: Without randomness, two calls with identical inputs will produce the same ID. +// +// Parameters: +// - prefix: The project prefix (e.g., "gt" for gastown, "bd" for beads) +// - branch: The source branch name (e.g., "polecat/Nux/gt-xyz") +// - timestamp: The time to use for ID generation instead of time.Now() +// +// Returns a string in the format "-mr-<6-char-hash>" func GenerateMRIDWithTime(prefix, branch string, timestamp time.Time) string { return generateMRIDInternal(prefix, branch, timestamp, nil) } diff --git a/internal/runtime/runtime.go b/internal/runtime/runtime.go index e26be5f0..c27fd9b8 100644 --- a/internal/runtime/runtime.go +++ b/internal/runtime/runtime.go @@ -84,6 +84,13 @@ func RunStartupFallback(t *tmux.Tmux, sessionID, role string, rc *config.Runtime return nil } +// isAutonomousRole returns true if the given role should automatically +// inject mail check on startup. Autonomous roles (polecat, witness, +// refinery, deacon) operate without human prompting and need mail injection +// to receive work assignments. +// +// Non-autonomous roles (mayor, crew) are human-guided and should not +// have automatic mail injection to avoid confusion. func isAutonomousRole(role string) bool { switch role { case "polecat", "witness", "refinery", "deacon":