service#

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

Package service manages the platform-native auto-restart definition for the durable radioactive_ralph supervisor process.

The rewritten runtime (docs/superpowers/specs/2026-07-16-supervisor-architecture-design.md §4-§6) is a SINGLE per-user supervisor keyed off the XDG state root, not a per-repo daemon — so there is exactly one service definition per user per machine, not one per repo. Installing it makes `radioactive_ralph –supervisor` a long-running, auto-restarting background process managed by the platform’s native service host instead of something the operator has to remember to start by hand in a terminal.

Platform dispatch:

  • macOS → launchd user agent

  • Linux/WSL → systemd user unit

  • Windows → native Service Control Manager entry

Service-context detection is used to distinguish durable service launches from operator-attached foreground invocations.

Index#

Variables#

ErrMissingRalphBin is returned when RalphBin is empty.

var ErrMissingRalphBin = errors.New("service: RalphBin required")

ErrUnsupportedBackend is returned for platforms we don’t manage.

var ErrUnsupportedBackend = errors.New("service: unsupported platform")

func Install#

func Install(opts InstallOptions) (path string, err error)

Install writes or registers the platform service definition that runs `radioactive_ralph –supervisor` as a per-user auto-restarting background process. On launchd/systemd this means writing the unit file; on Windows it also registers the SCM entry.

func IsServiceContext#

func IsServiceContext() bool

IsServiceContext reports whether the current process looks like it’s running under the durable per-user service host rather than an operator-attached foreground invocation.

func MarshalWindowsServiceConfig#

func MarshalWindowsServiceConfig(opts InstallOptions) ([]byte, error)

MarshalWindowsServiceConfig renders the Windows service config in the exact JSON form written to disk for the native service host.

func Start#

func Start(opts InstallOptions) error

Start loads/starts the installed per-user supervisor service so its process actually comes up. Install only WRITES the unit definition; on launchd and systemd the unit must additionally be loaded/started (a launchd unit with RunAtLoad still needs `launchctl bootstrap`; systemd needs `systemctl –user start`). Windows SCM’s install already starts it, so Start is a no-op there. Returns nil when the start command succeeds or the platform needs no separate start.

func Uninstall#

func Uninstall(opts InstallOptions) error

Uninstall removes the unit file. Returns nil if already absent.

func UnitName#

func UnitName(b Backend) string

UnitName is the single, stable name for the per-user supervisor service definition — there is exactly one per user per machine, so unlike the old per-repo scheme this takes no arguments.

launchd:     "jbcom.radioactive-ralph.supervisor"
systemd:     "radioactive_ralph-supervisor"
windows-scm: "radioactive_ralph-supervisor"

func UnitPath#

func UnitPath(b Backend, home string) string

UnitPath returns the on-disk path where the unit file will be written. Callers pass the operator’s home dir (tests inject a tmpdir).

func WindowsServiceArgs#

func WindowsServiceArgs() []string

WindowsServiceArgs returns the radioactive_ralph argv used by the native Windows SCM service entry: just –supervisor, since the per-user supervisor takes no repo-scoped arguments.

type Backend#

Backend identifies which platform mechanism is in use.

type Backend string


const (
    // BackendLaunchd is macOS per-user launchd agent.
    BackendLaunchd Backend = "launchd"
    // BackendSystemdUser is Linux/WSL systemd user unit.
    BackendSystemdUser Backend = "systemd-user"
    // BackendWindowsSCM is a native Windows service managed by the Service
    // Control Manager.
    BackendWindowsSCM Backend = "windows-scm"
    // BackendUnsupported is returned for platforms we don't manage.
    BackendUnsupported Backend = "unsupported"
)

func DetectBackend#

func DetectBackend() Backend

DetectBackend returns the appropriate backend for the current OS.

type InstallOptions#

InstallOptions configures an install.

type InstallOptions struct {
    // Backend overrides the detected platform. Empty = detect.
    Backend Backend
    // HomeDir overrides os.UserHomeDir. Empty = use os.UserHomeDir().
    HomeDir string
    // RalphBin is the absolute path to the radioactive_ralph binary that
    // the unit should exec (with --supervisor). Required.
    RalphBin string
    // ExtraEnv is merged into the unit's environment block. Callers use
    // this for RALPH_STATE_DIR, RALPH_SPEND_CAP_USD, etc.
    ExtraEnv map[string]string
}

type Status#

Status reports whether the per-user supervisor service definition is installed. This only inspects the service definition on disk (unit file present/absent); it says nothing about whether the supervisor process is currently running — callers wanting liveness should combine this with supervisor.Find against the XDG state root.

type Status struct {
    Backend   Backend
    Installed bool
    UnitPath  string
}

func Inspect#

func Inspect(opts InstallOptions) (Status, error)

Inspect reports the current install status of the per-user supervisor service definition for the detected (or overridden) backend.

type WindowsServiceConfig#

WindowsServiceConfig is the persisted config payload used by the native Windows service host for the per-user supervisor service.

type WindowsServiceConfig struct {
    ExtraEnv map[string]string `json:"extra_env,omitempty"`
}

func BuildWindowsServiceConfig#

func BuildWindowsServiceConfig(opts InstallOptions) WindowsServiceConfig

BuildWindowsServiceConfig produces the persisted config payload for the supervisor service instance.

func ParseWindowsServiceConfig#

func ParseWindowsServiceConfig(raw []byte) (WindowsServiceConfig, error)

ParseWindowsServiceConfig parses the persisted Windows service config JSON.

Generated by gomarkdoc