go-process

Module: forge.lthn.ai/core/go-process

Process management with Core IPC integration. Provides spawning, monitoring, and controlling external processes with output streaming via the Core ACTION system. Includes PID file management, health check servers, daemon lifecycle, and a daemon registry.

Architecture

File	Purpose
`types.go`	`Status`, `Stream`, `RunOptions`, `Info` types
`process.go`	`Process` struct — managed external process with output capture
`runner.go`	Process runner — starts processes with ring buffer capture
`service.go`	Core service integration — registers with Core DI container
`pidfile.go`	`PIDFile` — single-instance enforcement via lock files
`health.go`	`HealthServer` — HTTP `/health` and `/ready` endpoints
`daemon.go`	`Daemon` — lifecycle manager combining PID file + health + registry
`registry.go`	`Registry` — tracks running daemons via JSON files in `~/.core/daemons/`
`buffer.go`	`RingBuffer` — fixed-size circular buffer for output capture
`actions.go`	IPC action types for process events
`exec/`	`exec.Exec` — simple command execution helper

Key Types

Process Management

Process — Running process: ID, Command, Args, Dir, Env, Status, ExitCode. Methods: Wait(), Done(), Kill(), Signal(), SendInput(), CloseStdin(), Output(), Info(), IsRunning()
Status — StatusPending, StatusRunning, StatusExited, StatusFailed, StatusKilled
RunOptions — Command, Args, Dir, Env, DisableCapture
Info — Snapshot of process state (serialisable): ID, Command, Args, PID, Status, ExitCode, Duration
RingBuffer — Circular output buffer: Write(), String(), Bytes()

Daemon Lifecycle

Daemon — Manages PID file + health server + registry: Start(), Run() (blocks until context cancelled), Stop(), SetReady(), HealthAddr()
DaemonOptions — PIDFile, ShutdownTimeout (default 30s), HealthAddr, HealthChecks, Registry, RegistryEntry
PIDFile — Acquire(), Release(), IsLocked(), ReadPID()
HealthServer — HTTP server at /health (checks) and /ready (readiness): Start(), Stop(), AddCheck(), SetReady(), Addr()
HealthCheck — func() error — returns nil if healthy

Daemon Registry

Registry — JSON file-based daemon tracker: Register(), Unregister(), Get(), List()
DaemonEntry — Code, Daemon, PID, Health, Project, Binary, Started
DefaultRegistry() — Uses ~/.core/daemons/
Stale entries (dead PIDs) are automatically pruned on Get() and List()

Usage

import "forge.lthn.ai/core/go-process"

// Daemon mode
daemon := process.NewDaemon(process.DaemonOptions{
    PIDFile:     "/var/run/myapp.pid",
    HealthAddr:  ":9090",
    Registry:    process.DefaultRegistry(),
    RegistryEntry: process.DaemonEntry{Code: "myapp", Daemon: "server"},
})
daemon.Start()
daemon.SetReady(true)
daemon.Run(ctx) // blocks until ctx cancelled

// Health check polling
ok := process.WaitForHealth("localhost:9090", 5000) // 5s timeout

Dependencies

github.com/stretchr/testify — Tests only
No core ecosystem dependencies