daemon

Documentation

Overview

Package daemon runs the user-level agentd process: start, stop, lock, status, reload, and login autostart registration.

Owns: process lifecycle, single-instance lock, status JSON, SIGHUP reload signal, operational slog setup (SetupLog), login autostart (Enable, Disable, AutostartStatus), opt-in Prometheus metrics HTTP listen lifecycle. Must not: hook dispatch (dispatch), config compile (config), gRPC handlers (server).

Invariants:

• One daemon per user (lock file).
• Reload is debounced in config.Store, not here.
• Logger configured once at startup; default log file under state dir.
• Disable removes OS autostart only; never stops a running daemon.

Entry: Start, Stop, Enable, Disable, AutostartStatus, WriteStatus, SetupLog. See DESIGN.md §1.5 (config_reload).

Index

• Variables
• func ClaudeProjectsRootForTest(configured string) string
• func Disable() error
• func Enable(ctx context.Context, opts AutostartOptions) error
• func ReleaseLock(f *os.File)
• func SetAutostartHooksForTest(h *AutostartHooks) func()
• func SetupLog(opts SetupLogOptions) (*slog.Logger, func(), error)
• func Start(ctx context.Context, opts StartOptions) error
• func Stop(ctx context.Context, socket string, timeout time.Duration) error
• func WriteStatus(w io.Writer, rep StatusReport, asJSON bool) error
• type AutostartHooks
• type AutostartOptions
• type AutostartReport
  • func AutostartStatus() (AutostartReport, error)
• type AutostartSpec
• type Backend
• type ImportWatcher
  • func NewImportWatcher(store *config.Store, hub *trajectory.Hub, log *slog.Logger) *ImportWatcher
  • func (w *ImportWatcher) Start(ctx context.Context)
  • func (w *ImportWatcher) Stop()
• type Paths
  • func NewPaths(socket string) Paths
  • func (p Paths) AcquireLock() (*os.File, error)
  • func (p Paths) ClearPID()
  • func (p Paths) ReadPID() (int, error)
  • func (p Paths) RemoveStale()
  • func (p Paths) WritePID(pid int) error
• type ReloadResult
  • func Reload(ctx context.Context, socket string) (ReloadResult, error)
• type SetupLogOptions
• type StartOptions
• type StatusReport
  • func Status(ctx context.Context, socket string) (StatusReport, error)

Variables

var (
	// ErrAlreadyRunning means another daemon holds the lock or a live PID.
	ErrAlreadyRunning = errors.New("daemon already running")
	// ErrNotRunning means no daemon PID/socket was found.
	ErrNotRunning = errors.New("daemon not running")
	// ErrAutostartUnsupported means login autostart is not implemented on this GOOS.
	ErrAutostartUnsupported = errors.New("login autostart unsupported on this platform")
	// ErrAutostartNotAvailable means the OS user session backend is unavailable.
	ErrAutostartNotAvailable = errors.New("login autostart backend unavailable")
)

Functions

func ClaudeProjectsRootForTest

func ClaudeProjectsRootForTest(configured string) string

ClaudeProjectsRootForTest resolves Claude projects directory (exported for tests).

func Disable

func Disable() error

Disable removes login autostart registration. It does not stop a running daemon.

func Enable

func Enable(ctx context.Context, opts AutostartOptions) error

Enable registers login autostart and starts the daemon when it is not running.

func ReleaseLock

func ReleaseLock(f *os.File)

ReleaseLock unlocks and closes the lock file.

func SetAutostartHooksForTest

func SetAutostartHooksForTest(h *AutostartHooks) func()

SetAutostartHooksForTest overrides platform autostart hooks. For tests only.

func SetupLog

func SetupLog(opts SetupLogOptions) (*slog.Logger, func(), error)

SetupLog configures slog for the daemon process: append to a log file and optionally mirror to stderr in foreground mode. Returns cleanup to close the file and restore the previous default logger.

func Start

func Start(ctx context.Context, opts StartOptions) error

Start runs the daemon. In foreground mode it blocks until shutdown. When Foreground is false it re-execs/detaches and returns only after the child answers Health (or a readiness timeout).

func Stop

func Stop(ctx context.Context, socket string, timeout time.Duration) error

Stop asks a running daemon to shut down.

func WriteStatus

func WriteStatus(w io.Writer, rep StatusReport, asJSON bool) error

WriteStatus writes a StatusReport as JSON or a short human line.

Types

type AutostartHooks

type AutostartHooks struct {
	Register    func(AutostartSpec) error
	Unregister  func() error
	ReadState   func() (AutostartReport, error)
	ResolveExe  func() (string, error)
	StartIfDown func(context.Context, StartOptions) error
}

AutostartHooks overrides platform autostart I/O for tests. Nil fields use real OS hooks.

type AutostartOptions

type AutostartOptions struct {
	Socket     string
	ConfigPath string
	Version    string
}

AutostartOptions configures Enable.

type AutostartReport

type AutostartReport struct {
	Enabled       bool
	Backend       Backend
	ManifestPath  string
	RegisteredExe string
	Stale         bool
}

AutostartReport is the login autostart snapshot for status JSON.

func AutostartStatus

func AutostartStatus() (AutostartReport, error)

AutostartStatus reports whether login autostart is registered on this machine.

type AutostartSpec

type AutostartSpec struct {
	Exe  string
	Args []string
}

AutostartSpec holds the registered binary and service argv.

type Backend

type Backend string

Backend names login autostart integrations for status JSON.

const (
	BackendSystemd     Backend = "systemd"
	BackendLaunchd     Backend = "launchd"
	BackendSchtasks    Backend = "schtasks"
	BackendUnsupported Backend = ""
)

type ImportWatcher

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

ImportWatcher debounces Claude transcript imports (async_side; never blocks Invoke).

func NewImportWatcher

func NewImportWatcher(store *config.Store, hub *trajectory.Hub, log *slog.Logger) *ImportWatcher

NewImportWatcher returns a watcher tied to config reloads.

func (*ImportWatcher) Start

func (w *ImportWatcher) Start(ctx context.Context)

Start begins watching when claude import is enabled in the current snapshot.

func (*ImportWatcher) Stop

func (w *ImportWatcher) Stop()

Stop ends the background watcher.

type Paths

type Paths struct {
	Socket string
	PID    string
	Lock   string
	Dir    string
}

Paths holds filesystem locations for one daemon instance.

func NewPaths

func NewPaths(socket string) Paths

NewPaths derives state file paths from a socket path.

func (Paths) AcquireLock

func (p Paths) AcquireLock() (*os.File, error)

AcquireLock creates an exclusive lock file. Caller must ReleaseLock.

func (Paths) ClearPID

func (p Paths) ClearPID()

ClearPID removes the PID file so Stop waiters observe shutdown promptly.

func (Paths) ReadPID

func (p Paths) ReadPID() (int, error)

ReadPID reads the PID file.

func (Paths) RemoveStale

func (p Paths) RemoveStale()

RemoveStale removes PID and socket files after shutdown.

func (Paths) WritePID

func (p Paths) WritePID(pid int) error

WritePID writes the process ID to the pid file.

type ReloadResult

type ReloadResult struct {
	Generation  uint64
	Fingerprint string
}

ReloadResult is the config generation after a successful reload.

func Reload

func Reload(ctx context.Context, socket string) (ReloadResult, error)

Reload asks the running daemon to reload config from disk.

type SetupLogOptions

type SetupLogOptions struct {
	Logging    config.LoggingConfig
	Foreground bool
	LogLevel   string
	LogFile    string
}

SetupLogOptions configures daemon operational logging.

type StartOptions

type StartOptions struct {
	Socket        string
	ConfigPath    string
	Foreground    bool
	Version       string
	LogLevel      string
	LogFile       string
	MetricsListen string
}

StartOptions configures daemon Start.

type StatusReport

type StatusReport struct {
	Running                bool
	Socket                 string
	Version                string // process that answered Status, not this CLI binary
	StartedAt              time.Time
	Generation             uint64
	Fingerprint            string
	AsyncQueueDepth        uint32
	AsyncDroppedCount      uint64
	TrajectoryDroppedCount uint64
	CompiledRouteCount     uint32
	MetricsListen          string
	Autostart              AutostartReport
}

StatusReport is a snapshot of daemon liveness for CLI status.

func Status

func Status(ctx context.Context, socket string) (StatusReport, error)

Status probes the daemon and returns a StatusReport. When the daemon is unreachable, Running is false and other fields are zero (Socket is still set).