04 integration

§7d.4 Integration with the server

Wiring in cli/root.go

// Pseudocode — exact order matters for shutdown hooks.

supSvc, err := service.NewSupervisordService(service.SupervisordConfig{
    InitialState: defaultProcessState(selfPath, socketPath),
})
if err != nil { return err }

if err := supSvc.Start(ctx); err != nil {
    return fmt.Errorf("supervisord: %w", err)
}
go supSvc.RunHealthLoop(ctx, 5*time.Second)

// ScriptService receives supSvc for status + shutdown ordering
scriptSvc := service.NewScriptService(..., supSvc)

// … HTTP server, hub, etc.

// Shutdown (after SIGINT/SIGTERM):
scriptSvc.Shutdown(ctx)   // RPC drain, run.stop
supSvc.Stop(ctx)          // supervisorctl shutdown
srv.Shutdown(shutdownCtx)

SupervisordService is constructed before services that depend on managed processes. Shutdown reverses the order.

Replacing executor/supervisor.go

The hand-rolled supervisor planned in 04-repository-layout.md (pkgs/bigfred/server/executor/supervisor.go) is superseded by this component:

Keep pkgs/bigfred/server/executor/ for the RPC client/server (client.go, server.go, messages.go, codec.go). Remove supervisor.go from the plan — its responsibilities move to SupervisordService.

Cross-cutting doc §7 #12 should be updated after implementation to reference §7d instead of the hand-rolled spawn loop.

Managed Redis

loco-server boots its own redis-server under supervisord by default (group infra, program redis). Rationale:

• BigFred needs Redis for cross-process pub/sub and the loco:state cache. Asking operators to run a sibling daemon by hand reintroduces the very class of "is everything running?" foot-gun that supervisord exists to eliminate.
• The bundled instance binds to 127.0.0.1 only, persists with RDB only (--appendonly no, default save 60 100) to limit disk writes while keeping Redis state across restarts, and listens on port 6379 by default to avoid colliding with a pre-existing system Redis on :6379. Pass --redis-no-persist or --redis-rdb-save="" for ephemeral mode.
• Operators with their own Redis (e.g. shared between multiple BigFred installations, or running on another host) pass --redis-external --redis-addr host:port to skip the managed daemon. loco-server.WaitReady still blocks on PING before serving HTTP so a misconfigured external Redis fails fast.

CLI surface (all on loco-server):

Default process catalogue (M7 scripts milestone)

Rows added by M4.5 (§7e DCC bus daemon):

Future rows (post-M4.5):

Adding a row is one UpsertProgram call — no supervisord knowledge in the caller beyond ProgramSpec.

system.status WebSocket event

Extend the existing status payload:

{
  "type": "system.status",
  "payload": {
    "scriptsExecutor": "healthy",
    "supervisord": {
      "daemon": "running",
      "groups": {
        "loco": {
          "scripts-executor": {
            "status": "RUNNING",
            "pid": 12345,
            "uptimeSec": 3600
          }
        }
      }
    }
  }
}

Mapping rules:

• scriptsExecutor: "healthy" when program RUNNING and executor RPC socket accepts a connection (preserves current semantics).
• scriptsExecutor: "failed" when FATAL or daemon respawn policy gives up (same banner as §7 #12).
• supervisord.daemon: "degraded" when daemon respawn backoff exhausted.

Only diffs are broadcast on the health ticker to avoid WS noise.

Who calls Apply

M7 does not expose HTTP for process management. Dynamic CS workers are a later milestone.

Repository layout additions

Update 04-repository-layout.md when implementing:

pkgs/bigfred/server/supervisord/
    templates/supervisord.conf.tmpl
    config.go
    render.go
    ctl.go
    daemon.go
    render_test.go              # golden-file template tests

pkgs/bigfred/server/service/supervisord.go
pkgs/bigfred/server/service/supervisord_test.go   # fake supervisorctl in tests

Remove from the planned tree:

pkgs/bigfred/server/executor/supervisor.go   # deleted — replaced by §7d

Makefile / dev environment

Add to 12-makefile.md when implementing:

# Verify supervisord is available in dev/CI
check-supervisor:
    @command -v supervisord >/dev/null || (echo "install: pip install supervisor" && exit 1)

Document in 02-tech-stack.md:

Acceptance criteria (draft)

To be copied into 14-acceptance-criteria/ when the milestone is scheduled:

1. loco server as an unprivileged user creates /data paths, renders config, and starts supervisord without root.
2. supervisorctl -c /data/etc/supervisord/supervisord.conf status shows scripts-executor in RUNNING within 10 s of boot.
3. Changing desired state via Apply (add/remove program, toggle autostart) rewrites config and applies via reread + update without changing the supervisord daemon PID (hot reload).
4. Changing a program's command restarts only that program; siblings stay RUNNING.
5. kill -9 on a managed program with autorestart=true returns it to RUNNING without restarting loco server.
6. SIGTERM to loco server stops supervisord cleanly; no orphaned scripts-executor remains (ps check).
7. Template unit tests cover at least: empty groups, single group / single program, multiple groups, autostart=false, autorestart=false, shellQuote escaping for /bin/bash -c.