---
title: internal/supervisor
description: Go API reference for the supervisor package.
---

<!-- Code generated by gomarkdoc. DO NOT EDIT -->

# supervisor

```go
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>)
- [type Supervisor](<#Supervisor>)
  - [func New\(opts Options\) \(\*Supervisor, error\)](<#New>)
  - [func \(s \*Supervisor\) Run\(ctx context.Context\) error](<#Supervisor.Run>)
  - [func \(s \*Supervisor\) Shutdown\(\)](<#Supervisor.Shutdown>)


<a name="Options"></a>
## type [Options](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/supervisor/supervisor.go#L43-L61>)

Options configure a Supervisor.

```go
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
}
```

<a name="Supervisor"></a>
## type [Supervisor](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/supervisor/supervisor.go#L64-L80>)

Supervisor coordinates a single variant's run.

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

<a name="New"></a>
### func [New](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/supervisor/supervisor.go#L85>)

```go
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.

<a name="Supervisor.Run"></a>
### func \(\*Supervisor\) [Run](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/supervisor/supervisor.go#L116>)

```go
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.

<a name="Supervisor.Shutdown"></a>
### func \(\*Supervisor\) [Shutdown](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/supervisor/supervisor.go#L214>)

```go
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](<https://github.com/princjef/gomarkdoc>)