cmd/radioactive_ralph
import "github.com/jbcom/radioactive-ralph/cmd/radioactive_ralph"
Command radioactive_ralph is the one binary, two modes described in docs/superpowers/specs/2026-07-16-supervisor-architecture-design.md §4:
radioactive_ralph --supervisorruns the durable control-plane process — pty ownership, IPC, the single user-level store, the reaper. Working directory is irrelevant to it.- Plain
radioactive_ralphis a dumb client: it resolves the current directory's project, finds the running supervisor (or tells the operator how to start one), and talks to it. "Dumb" means it owns no ptys and no plan orchestration — not that it never touches the DB: it does open the shared user-level store to resolve/create the project row (the store's WAL + _txlock=immediate DSN is built for exactly this multi-process access). Project resolution may later move behind an IPC endpoint on the supervisor.
Variables
Version, Commit, and Date are set by GoReleaser at build time via -ldflags.
Source: cmd/radioactive_ralph/main.go:34
var (
Version = "dev"
Commit = "none"
Date = "unknown"
)Functions
func NewProviderCooldowns(now func() time.Time) *ProviderCooldowns
Source: cmd/radioactive_ralph/provider_cooldowns.go:53
NewProviderCooldowns creates an empty cooldown tracker. The now function defaults to time.Now and can be overridden in tests.
Types
type ProviderCooldowns
Source: cmd/radioactive_ralph/provider_cooldowns.go:25
ProviderCooldowns tracks per-provider rate-limit/credit-exhaustion cooldowns so the pool rotation can skip providers whose limits have reset but not yet been confirmed. When a provider fails with provider_auth or provider_rejected due to usage limits, it enters a cooldown with exponential backoff. When the cooldown expires, the next dispatch to it IS the probe — a success clears the cooldown, another failure extends it.
This is the mechanism that lets a multi-provider pool degrade gracefully: when claude credits run out, claude drops out of rotation and opencode/codex absorb the work. When claude's weekly limit resets, the cooldown expires and claude re-enters rotation automatically — no manual config change needed.
Thread-safe: the binding resolver and the orchestrator's failure path touch this from different goroutines.
type ProviderCooldowns struct {
// contains filtered or unexported fields
}func Active() map[string]time.Time
Source: cmd/radioactive_ralph/provider_cooldowns.go:105
Active returns the providers currently in cooldown (expiry not yet passed), along with when each one's cooldown ends. Used by the binding resolver to skip cooled providers in pool rotation.
func EarliestExpiry() string
Source: cmd/radioactive_ralph/provider_cooldowns.go:123
EarliestExpiry returns the provider with the soonest-expiring cooldown, or "" if no providers are in cooldown. Used when ALL providers are cooled — the resolver picks the earliest one so at least one dispatch can proceed after its cooldown ends.
func RecordFailure(providerName string, failure provider.Failure)
Source: cmd/radioactive_ralph/provider_cooldowns.go:76
RecordFailure extends a provider's cooldown after a failure that indicates rate-limiting or credit exhaustion. The failure category determines whether a cooldown is appropriate:
- provider_auth: the credential was rejected — a weekly/usage limit resets on a known schedule, so cooldown + probe is the right strategy.
- provider_rejected: the provider reported an unsuccessful turn. This includes quota/usage-limit messages that arrive as text rather than HTTP status codes.
Other failure categories (stall_timeout, turn_deadline, provider_unavailable, provider_throttled) are transient and handled by the retry budget — they do NOT enter cooldown because the provider is still functional, just temporarily unable to serve this turn.
func RecordSuccess(providerName string)
Source: cmd/radioactive_ralph/provider_cooldowns.go:96
RecordSuccess clears a provider's cooldown after a successful turn. A successful probe confirms the provider's limits have reset.
