ringmaster

The job platform: a durable job journal + wake-on-completion channel, and its MCP tool surface, extracted from clown into a standalone, forge-native Go module. It is upstream of both clown and troupe — troupe's messaging rides on the wake channel to notify sessions, and clown runs llama-server as a job over it.

What's here

• internal/0/jobwake/ — the substrate (Go-private), republished as the generated facade pkgs/jobwake/ (the public import code.linenisgreat.com/ringmaster/pkgs/jobwake): the JSONL job journal, the lossy UDS-datagram nudge, session-key/channel resolution, the output spool and status probe, the wake monitor, presence, and GC. Durable at-least-once correctness from disk; sub-second liveness from a best-effort socket. The facade is a thin dagnabit export re-export of the internal package's whole exported surface; nix flake check's facade-drift gate keeps the two in sync.
• jobmcp/ — the RFC-0011 MCP tool surface: a hand-rolled JSON-RPC stdio server exposing the job_* job-control tools over jobwake, served as ringmaster mcp. (Messaging — chat + job_message — moved to troupe, which serves its own chat MCP.)
• cmd/ringmaster/ — the job-control binary: producer verbs (start/progress/done/read/spool-path/wait/whoami), operator verbs (ls/status/tail/cancel), the version query (--protocol prints the on-disk layout protocol version consumers pin against), the per-session wake monitor, and the mcp server.

Messaging (chat, troupe send/read/list) lives in the separate troupe repo now; it builds on ringmaster's public pkgs/jobwake primitives and rides this wake channel to notify sessions.

The module is pure-stdlib (no third-party Go dependencies). On-disk state lives under $XDG_STATE_HOME/ringmaster/jobs/ with the nudge socket under $XDG_RUNTIME_DIR/ringmaster/jobs/.

Consuming ringmaster (igloo go-pkgs)

ringmaster is published via igloo's flake-input-go_mod protocol (RFC 0001). It exposes packages.${system}.go-pkgs and go-pkgs-test. A consumer bridges it as a Go dependency via goFlakeInputs on buildGoApplication/mkGoEnv:

# flake input
ringmaster.url = "git+https://code.linenisgreat.com/ringmaster.git";

# in the gomod.nix bridge
goFlakeInputs = {
  "code.linenisgreat.com/ringmaster" = {
    src = inputs.ringmaster.packages.${system}.go-pkgs;
  };
};

nix supplies the source through the bridge, so the module path code.linenisgreat.com/ringmaster is never fetched over the network (no GitHub mirror; the forge is SSOT). Consumers import the facade code.linenisgreat.com/ringmaster/pkgs/jobwake — the internal/0/jobwake substrate is Go-private and cannot be imported across the module boundary. A consumer that derives on-disk paths against ringmaster's namespace, or depends on its cancel/wait state machine, should also pin jobwake.ProtocolVersion and compare it against ringmaster version --protocol at start, degrading loudly on a mismatch (RFC-0018).

Build

nix build .#default        # ringmaster binary + manpages
nix flake check            # full gate: go tests + bats lanes + facade-drift
just                       # == nix flake check (the pre-merge gate)
just facade-export         # regenerate the pkgs/jobwake facade from internal/

Normative specs

The wire contracts are specified in docs/rfcs/: RFC-0009 (wakeup channel), RFC-0010 (output spool + status), RFC-0011 (MCP tools), and RFC-0015 (the ringmaster/troupe binary surface) — migrated here from clown's docs/rfcs/ so the standalone repo owns its own contracts — plus RFC-0016 (producer liveness + job identity) and RFC-0017 (job-id grammar), the ringmaster-originated contracts. See docs/rfcs/README.md for the numbering scheme.