supervisor

import "github.com/jbcom/radioactive-ralph/internal/supervisor"

Package supervisor is the per-variant brain of radioactive-ralph.

One Supervisor instance runs per live `radioactive_ralph run –variant X` invocation. It owns:

  • A PID flock at Paths.Sessions/<variant>.pid so only one Supervisor-per-variant runs at a time in the same repo.

  • The Unix socket listener at Paths.Sessions/<variant>.sock and its heartbeat marker .alive.

  • The SQLite event log at Paths.StateDB. On boot, the event log is replayed to rebuild in-memory state.

  • The workspace.Manager that owns mirror/worktree lifecycle.

  • The session pool of claude subprocesses.

Lifecycle:

New()         → resolve state paths, validate variant
Run(ctx)      → blocks; does flock acquire, db open, socket bind,
                event replay, workspace init, session pool spawn,
                IPC request loop; returns nil on graceful shutdown
                or a descriptive error on startup failure.
Shutdown(ctx) → asks the running supervisor to stop gracefully.

Index

type Options

Options configure a Supervisor.

type Options struct {
    // RepoPath is the operator's repo (mandatory).
    RepoPath string

    // Variant profile to drive. Mandatory.
    Variant variant.Profile

    // Workspace is the workspace manager for this variant run. Caller
    // constructs it (we can't — it needs resolved knobs from config).
    Workspace *workspace.Manager

    // HeartbeatInterval controls how often the supervisor touches the
    // .alive file. Default 10s.
    HeartbeatInterval time.Duration

    // ShutdownTimeout is the max wall time to wait for graceful
    // shutdown before force-killing sessions. Default 30s.
    ShutdownTimeout time.Duration
}

type Supervisor

Supervisor coordinates a single variant’s run.

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

func New

func New(opts Options) (*Supervisor, error)

New constructs a Supervisor without starting it. Returns an error if the options are structurally invalid; all runtime failures surface from Run.

func (*Supervisor) Run

func (s *Supervisor) Run(ctx context.Context) error

Run blocks until the supervisor shuts down. Returns nil for a graceful stop, error for any startup or fatal runtime failure.

func (*Supervisor) Shutdown

func (s *Supervisor) Shutdown()

Shutdown requests a graceful stop. Safe to call from a signal handler or another goroutine. Run() returns after internal cleanup completes.

Generated by gomarkdoc