relay-flow 0.0.1 → 0.2.0-alpha

package/cmd/relay-flow/main.go

@@ -1,250 +1,740 @@
-// Command relay-flow automates tracker ↔ runner agent workflows.
-// `serve` is a central process hosting any number of workflows submitted via
-// `submit`. `report` is a one-shot socket client (invoked by the opencode
-// plugin) that asks the server to record an agent outcome.
+// Command relay-flow is the entrypoint. It is a thin command parser
+// (standard flag package) with zero business logic: every command
+// delegates to the server client (internal/server.Client) or the
+// section-5 composition root for init/serve. The testable entry is
+// run(args, stdin) int (allowed seam e).
 package main
 
 import (
+	"bufio"
+	"context"
 	"encoding/json"
 	"flag"
 	"fmt"
 	"io"
-	"log"
-	"net"
 	"os"
-	"os/exec"
 	"os/signal"
 	"path/filepath"
-
+	"strings"
 	"syscall"
+	"time"
 
-	"github.com/rajpopat27/relay-flow/internal/acli"
+	"github.com/charmbracelet/huh"
+	"github.com/mattn/go-isatty"
 	"github.com/rajpopat27/relay-flow/internal/config"
-	"github.com/rajpopat27/relay-flow/internal/discovery"
+	"github.com/rajpopat27/relay-flow/internal/execution/goworkflows"
+	"github.com/rajpopat27/relay-flow/internal/harness"
+	"github.com/rajpopat27/relay-flow/internal/logging"
+	"github.com/rajpopat27/relay-flow/internal/paths"
+	"github.com/rajpopat27/relay-flow/internal/repo"
+	runsvc "github.com/rajpopat27/relay-flow/internal/run"
+	"github.com/rajpopat27/relay-flow/internal/runner"
 	"github.com/rajpopat27/relay-flow/internal/server"
+	"github.com/rajpopat27/relay-flow/internal/task"
+
+	// Adapter registrations (factories registered via init for plugin
+	// name validation at init-time).
+	_ "github.com/rajpopat27/relay-flow/internal/harness/opencode"
+	_ "github.com/rajpopat27/relay-flow/internal/runner/orca"
+	_ "github.com/rajpopat27/relay-flow/internal/task/jira"
 )
 
-func main() {
-	if len(os.Args) < 2 {
-		usage()
-		os.Exit(1)
+// Exit codes per specs/workflow-repo-management "CLI exit codes are
+// stable": 0 success, 2 command/flag usage, 1 server/validation/operation.
+const (
+	exitOK    = 0
+	exitFail  = 1
+	exitUsage = 2
+)
+
+func main() { os.Exit(run(os.Args[1:], os.Stdin)) }
+
+// home returns the relay-flow root, honoring RELAY_FLOW_HOME (tests and
+// non-standard installs) and falling back to ~/.relay-flow.
+func home() (paths.Paths, error) {
+	if env := os.Getenv("RELAY_FLOW_HOME"); env != "" {
+		root := env
+		return paths.Paths{
+			Root:      root,
+			Config:    filepath.Join(root, "config.yaml"),
+			Workflows: filepath.Join(root, "workflows"),
+			Database:  filepath.Join(root, "state.db"),
+			Socket:    filepath.Join(root, "server.sock"),
+			Lock:      filepath.Join(root, "server.lock"),
+			ServerLog: filepath.Join(root, "server.log"),
+			PluginLog: filepath.Join(root, "plugin.log"),
+		}, nil
 	}
-	switch os.Args[1] {
+	return paths.ForUserHome()
+}
+
+// run parses args and dispatches one command. It is the test seam: stdin
+// is injectable so the report command can be driven in-process.
+func run(args []string, stdin io.Reader) int {
+	if len(args) == 0 {
+		usage(os.Stderr)
+		return exitUsage
+	}
+	p, err := home()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		return exitFail
+	}
+	client := server.NewClient(p.Socket)
+
+	switch args[0] {
 	case "init":
-		cmdInit(os.Args[2:])
-	case "stop":
-		cmdStop(os.Args[2:])
+		return cmdInit(p, args[1:], stdin)
 	case "serve":
-		cmdServe(os.Args[2:])
-	case "submit":
-		cmdSubmit(os.Args[2:])
+		return cmdServe(p, args[1:])
+	case "stop":
+		fs := flag.NewFlagSet("stop", flag.ContinueOnError)
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		if err := client.Stop(context.Background()); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		return exitOK
 	case "report":
-		cmdReport(os.Args[2:])
+		fs := flag.NewFlagSet("report", flag.ContinueOnError)
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		return cmdReport(client, stdin)
+	case "runtime-register":
+		fs := flag.NewFlagSet("runtime-register", flag.ContinueOnError)
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		return cmdRuntimeRegister(client, stdin)
+	case "workflow":
+		return cmdWorkflow(client, args[1:])
+	case "repo":
+		return cmdRepo(client, args[1:], stdin)
+	case "run":
+		return cmdRun(client, args[1:])
 	default:
-		usage()
-		os.Exit(1)
+		usage(os.Stderr)
+		return exitUsage
 	}
 }
 
-func usage() {
-	fmt.Fprintln(os.Stderr, "usage: relay-flow init --assignee \"<your Jira display name or accountId>\"")
-	fmt.Fprintln(os.Stderr, "       relay-flow stop serve")
-	fmt.Fprintln(os.Stderr, "       relay-flow serve [--dry-run] [--foreground]")
-	fmt.Fprintln(os.Stderr, "       relay-flow submit [-f <yaml>]   (workflow name comes from the YAML's name field)")
-	fmt.Fprintln(os.Stderr, "       relay-flow report --workflow <name> --ticket <key> --node <node> --outcome <success|failure> --summary <text>")
-	fmt.Fprintln(os.Stderr, "  server artifacts (lock/sock/log) are always under ~/.relay-flow/")
+func usage(w io.Writer) {
+	fmt.Fprintln(w, `relay-flow — durable ticket runner
+
+Usage:
+  relay-flow init [--task-plugin <name> --runner-plugin <name> --harness-plugin <name>]
+  relay-flow serve [--recover] [--debug]
+  relay-flow stop
+  relay-flow report
+
+  relay-flow workflow submit --file <path>
+  relay-flow workflow remove --name <name>
+  relay-flow workflow list
+  relay-flow workflow get --name <name>
+
+  relay-flow repo register [--name <name> --path <path> --set key=value ...]
+  relay-flow repo remove --name <name>
+  relay-flow repo list
+  relay-flow repo get --name <name>
+
+  relay-flow run list
+  relay-flow run get --ticket <key>
+  relay-flow run cancel --ticket <key>`)
 }
 
-// daemonize re-execs the binary detached with childArgs, log file attached
-// as stdout+stderr. No supervisor, no IPC: the child IS the worker. Returns
-// after spawning.
-func daemonize(logPath string, childArgs ...string) {
-	f, err := os.OpenFile(logPath, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o644)
-	if err != nil {
-		log.Fatalf("open log file: %v", err)
+// --- init / serve delegate to the section-5 composition root ---
+
+// cmdInit is the init composition root (docs lines 950/1028): select the
+// three plugin names, atomically write the machine config, and initialize
+// the SQLite database. Refuses to overwrite existing config or history.
+// Plugin selection precedence: --task-plugin/--runner-plugin/--harness-plugin
+// flags (all three required for a fully non-interactive run) → huh form on
+// a TTY → three stdin lines (task, runner, harness), the documented test
+// seam and script path.
+func cmdInit(p paths.Paths, args []string, stdin io.Reader) int {
+	fs := flag.NewFlagSet("init", flag.ContinueOnError)
+	taskName := fs.String("task-plugin", "", "task plugin name (non-interactive)")
+	runnerName := fs.String("runner-plugin", "", "runner plugin name (non-interactive)")
+	harnessName := fs.String("harness-plugin", "", "harness plugin name (non-interactive)")
+	if err := fs.Parse(args); err != nil {
+		return exitUsage
 	}
-	self, err := os.Executable()
-	if err != nil {
-		log.Fatalf("resolve executable: %v", err)
+	flagged := *taskName != "" || *runnerName != "" || *harnessName != ""
+	if flagged && (*taskName == "" || *runnerName == "" || *harnessName == "") {
+		fmt.Fprintln(os.Stderr, "init: --task-plugin, --runner-plugin, and --harness-plugin must be given together")
+		return exitUsage
+	}
+	// Refuse to overwrite existing state.
+	if _, err := os.Stat(p.Config); err == nil {
+		fmt.Fprintln(os.Stderr, "init: already initialized (config exists): "+p.Config)
+		return exitFail
+	}
+	if _, err := os.Stat(p.Database); err == nil {
+		fmt.Fprintln(os.Stderr, "init: already initialized (database exists): "+p.Database)
+		return exitFail
+	}
+	if err := os.MkdirAll(p.Root, 0o700); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		return exitFail
+	}
+	_ = os.Chmod(p.Root, 0o700)
+
+	// Selection precedence: flags → TTY form → stdin lines. The stdin path
+	// is the documented test seam and script path.
+	var names []string
+	switch {
+	case flagged:
+		names = []string{*taskName, *runnerName, *harnessName}
+	case isTTY(stdin):
+		var err error
+		names, err = pickPluginsInteractive()
+		if err != nil {
+			fmt.Fprintln(os.Stderr, "init: "+err.Error())
+			return exitFail
+		}
+	default:
+		names = readPluginLines(stdin)
+		if names == nil {
+			fmt.Fprintln(os.Stderr, "init: expected three plugin selections (task, runner, harness) on stdin")
+			return exitFail
+		}
+	}
+	// Validate against the registered factories; unknown names list the
+	// registered set per design (no silent acceptance).
+	if err := task.ValidateName(names[0]); err != nil {
+		fmt.Fprintln(os.Stderr, "init: task plugin: "+err.Error())
+		return exitFail
+	}
+	if err := runner.ValidateName(names[1]); err != nil {
+		fmt.Fprintln(os.Stderr, "init: runner plugin: "+err.Error())
+		return exitFail
 	}
-	cmd := exec.Command(self, childArgs...)
-	cmd.Stdout, cmd.Stderr = f, f
-	cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
-	cmd.Env = append(os.Environ(), "RELAY_FLOW_DAEMONIZED=1")
-	if err := cmd.Start(); err != nil {
-		log.Fatalf("daemonize: %v", err)
+	if err := harness.ValidateName(names[2]); err != nil {
+		fmt.Fprintln(os.Stderr, "init: harness plugin: "+err.Error())
+		return exitFail
+	}
+
+	cfg := &config.Machine{
+		TaskPlugin:         names[0],
+		RunnerPlugin:       names[1],
+		HarnessPlugin:      names[2],
+		KeepTerminalsAlive: true,
+		KeepSessionsAlive:  true,
 	}
-	fmt.Printf("started (pid %d), logging to %s\n", cmd.Process.Pid, logPath)
+	if err := config.SaveMachine(p.Config, cfg); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		return exitFail
+	}
+	if err := goworkflows.InitDatabase(p.Database); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		return exitFail
+	}
+	return exitOK
+}
+
+// isTTY reports whether stdin is an interactive terminal.
+func isTTY(stdin io.Reader) bool {
+	f, ok := stdin.(*os.File)
+	return ok && isatty.IsTerminal(f.Fd())
 }
 
-// cmdInit writes the machine config (~/.relay-flow/config.yaml) with this machine
-// user's tracker identity, probe-validated against the tracker.
-func cmdInit(args []string) {
-	fs := flag.NewFlagSet("init", flag.ExitOnError)
-	assignee := fs.String("assignee", "", "your tracker display name or accountId")
-	fs.Parse(args)
-	if *assignee == "" {
-		log.Fatalf("usage: relay-flow init --assignee \"<your tracker display name or accountId>\"")
+// pickPluginsInteractive runs the huh form: one searchable select per
+// plugin (task, runner, harness); enter advances/submits.
+func pickPluginsInteractive() ([]string, error) {
+	names := make([]string, 3)
+	form := huh.NewForm(
+		huh.NewGroup(huh.NewSelect[string]().
+			Title("Task plugin").
+			Options(huh.NewOptions(task.Names()...)...).
+			Filtering(true).
+			Value(&names[0])),
+		huh.NewGroup(huh.NewSelect[string]().
+			Title("Runner plugin").
+			Options(huh.NewOptions(runner.Names()...)...).
+			Filtering(true).
+			Value(&names[1])),
+		huh.NewGroup(huh.NewSelect[string]().
+			Title("Harness plugin").
+			Options(huh.NewOptions(harness.Names()...)...).
+			Filtering(true).
+			Value(&names[2])),
+	)
+	if err := form.Run(); err != nil {
+		return nil, err
 	}
-	if err := acli.New().ValidateAssignee(*assignee); err != nil {
-		log.Fatalf("%v", err)
+	return names, nil
+}
+
+// readPluginLines reads the three plugin names from stdin, one per line
+// (task, runner, harness); trailing whitespace tolerated. Returns nil when
+// fewer than three non-empty lines are present.
+func readPluginLines(stdin io.Reader) []string {
+	names := make([]string, 0, 3)
+	scanner := bufio.NewScanner(stdin)
+	for len(names) < 3 && scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+		names = append(names, line)
 	}
-	if err := (&config.MachineConfig{Assignee: *assignee}).Save(); err != nil {
-		log.Fatalf("%v", err)
+	if len(names) != 3 {
+		return nil
 	}
-	p, _ := config.MachineConfigPath()
-	fmt.Printf("machine config written to %s (assignee=%q)\n", p, *assignee)
+	return names
 }
 
-func cmdStop(args []string) {
-	// `stop serve` asks the central server to shut down over its socket;
-	// process exit releases the flock, so no pid file exists to clean up.
-	if len(args) != 1 || args[0] != "serve" {
-		log.Fatalf("usage: relay-flow stop serve")
+func cmdServe(p paths.Paths, args []string) int {
+	fs := flag.NewFlagSet("serve", flag.ContinueOnError)
+	recover := fs.Bool("recover", false, "treat execution state as lost and rebuild from the task system")
+	debug := fs.Bool("debug", false, "enable debug logging (overrides RELAY_FLOW_LOG_LEVEL)")
+	if err := fs.Parse(args); err != nil {
+		return exitUsage
 	}
-	client, err := server.NewClient()
+	logCloser, err := logging.Setup(p.ServerLog, logging.Options{
+		Debug: *debug,
+		Env:   os.Getenv("RELAY_FLOW_LOG_LEVEL"),
+	})
 	if err != nil {
-		log.Fatalf("%v", err)
+		fmt.Fprintln(os.Stderr, err)
+		return exitFail
 	}
-	if err := client.Shutdown(); err != nil {
-		log.Fatalf("%v", err)
+	defer logCloser.Close()
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+	if err := serveRoot(ctx, p, *recover); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		return exitFail
 	}
-	fmt.Println("server stopped")
+	return exitOK
 }
 
-// cmdServe runs the central server: one process hosting any number of
-// workflows submitted over its unix socket. Daemonizes by default.
-func cmdServe(args []string) {
-	fs := flag.NewFlagSet("serve", flag.ExitOnError)
-	dryRun := fs.Bool("dry-run", false, "log every runner command instead of executing it")
-	foreground := fs.Bool("foreground", false, "stay in the foreground")
-	fs.Parse(args)
+// --- report ---
 
-	home, err := os.UserHomeDir()
+// cmdReport reads one JSON object from stdin and posts it to /reports.
+// Exit 0 on any ack (including duplicate/stale), 1 on server/validation
+// failure or malformed JSON.
+func cmdReport(c *server.Client, stdin io.Reader) int {
+	body, err := io.ReadAll(stdin)
 	if err != nil {
-		log.Fatalf("%v", err)
+		fmt.Fprintln(os.Stderr, err)
+		return exitFail
+	}
+	var req runsvc.ReportRequest
+	if err := json.Unmarshal(body, &req); err != nil {
+		fmt.Fprintln(os.Stderr, "report: malformed JSON: "+err.Error())
+		return exitFail
 	}
-	logPath := filepath.Join(home, ".relay-flow", "server.log")
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	if _, err := c.SubmitReport(ctx, req); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		return exitFail
+	}
+	return exitOK
+}
 
-	if !*foreground {
-		// Acquire the single-instance lock in the PARENT, before spawning:
-		// this is where the user is watching, so "already running" must
-		// fail here, not silently in the detached child.
-		release, err := discovery.AcquireServerLock()
+// cmdRuntimeRegister reads one plugin-owned JSON session registration from
+// stdin and forwards it to the server over the existing Unix socket.
+func cmdRuntimeRegister(c *server.Client, stdin io.Reader) int {
+	body, err := io.ReadAll(stdin)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		return exitFail
+	}
+	var registration runsvc.NodeRuntimeRegistration
+	if err := json.Unmarshal(body, &registration); err != nil {
+		fmt.Fprintln(os.Stderr, "runtime-register: malformed JSON: "+err.Error())
+		return exitFail
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	if _, err := c.RegisterNodeSession(ctx, registration); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		return exitFail
+	}
+	return exitOK
+}
+
+// --- workflow ---
+
+func cmdWorkflow(c *server.Client, args []string) int {
+	if len(args) == 0 {
+		usage(os.Stderr)
+		return exitUsage
+	}
+	switch args[0] {
+	case "submit":
+		fs := flag.NewFlagSet("workflow submit", flag.ContinueOnError)
+		file := fs.String("file", "", "workflow YAML file")
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		if *file == "" {
+			fmt.Fprintln(os.Stderr, "workflow submit: --file is required")
+			return exitUsage
+		}
+		body, err := os.ReadFile(*file)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		wf, err := c.SubmitWorkflow(context.Background(), body)
 		if err != nil {
-			log.Fatalf("%v", err)
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		fmt.Println(wf.Name)
+		return exitOK
+	case "remove":
+		fs := flag.NewFlagSet("workflow remove", flag.ContinueOnError)
+		name := fs.String("name", "", "workflow name")
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
 		}
-		release()
-		childArgs := []string{"serve", "--foreground"}
-		if *dryRun {
-			childArgs = append(childArgs, "--dry-run")
+		if *name == "" {
+			fmt.Fprintln(os.Stderr, "workflow remove: --name is required")
+			return exitUsage
+		}
+		if err := c.RemoveWorkflow(context.Background(), *name); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		return exitOK
+	case "list":
+		fs := flag.NewFlagSet("workflow list", flag.ContinueOnError)
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		wfs, err := c.ListWorkflows(context.Background())
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
 		}
-		daemonize(logPath, childArgs...)
-		return
+		for _, wf := range wfs {
+			fmt.Println(wf.Name)
+		}
+		return exitOK
+	case "get":
+		fs := flag.NewFlagSet("workflow get", flag.ContinueOnError)
+		name := fs.String("name", "", "workflow name")
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		if *name == "" {
+			fmt.Fprintln(os.Stderr, "workflow get: --name is required")
+			return exitUsage
+		}
+		wf, err := c.GetWorkflow(context.Background(), *name)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		enc := json.NewEncoder(os.Stdout)
+		enc.SetIndent("", "  ")
+		_ = enc.Encode(wf)
+		return exitOK
 	}
+	usage(os.Stderr)
+	return exitUsage
+}
+
+// --- repo ---
 
-	// Tee logs to server.log when run interactively; daemonized child
-	// already has stderr attached to the log file.
-	if os.Getenv("RELAY_FLOW_DAEMONIZED") == "" {
-		if f, err := os.OpenFile(logPath, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o644); err == nil {
-			log.SetOutput(io.MultiWriter(os.Stderr, f))
-			defer f.Close()
+func cmdRepo(c *server.Client, args []string, stdin io.Reader) int {
+	if len(args) == 0 {
+		usage(os.Stderr)
+		return exitUsage
+	}
+	switch args[0] {
+	case "register":
+		fs := flag.NewFlagSet("repo register", flag.ContinueOnError)
+		name := fs.String("name", "", "repo name (non-interactive)")
+		path := fs.String("path", "", "repo path (non-interactive)")
+		sets := kvFlags{}
+		fs.Var(&sets, "set", "required task repo key value, key=value (repeatable)")
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		return cmdRepoRegister(c, *name, *path, sets, stdin)
+	case "remove":
+		fs := flag.NewFlagSet("repo remove", flag.ContinueOnError)
+		name := fs.String("name", "", "repo name")
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		if *name == "" {
+			fmt.Fprintln(os.Stderr, "repo remove: --name is required")
+			return exitUsage
+		}
+		if err := c.RemoveRepo(context.Background(), *name); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		return exitOK
+	case "list":
+		fs := flag.NewFlagSet("repo list", flag.ContinueOnError)
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		infos, err := c.ListRepos(context.Background())
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		for _, info := range infos {
+			fmt.Println(info.Name)
+		}
+		return exitOK
+	case "get":
+		fs := flag.NewFlagSet("repo get", flag.ContinueOnError)
+		name := fs.String("name", "", "repo name")
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		if *name == "" {
+			fmt.Fprintln(os.Stderr, "repo get: --name is required")
+			return exitUsage
 		}
+		info, err := c.GetRepo(context.Background(), *name)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		enc := json.NewEncoder(os.Stdout)
+		enc.SetIndent("", "  ")
+		_ = enc.Encode(info)
+		return exitOK
 	}
+	usage(os.Stderr)
+	return exitUsage
+}
 
-	// Single instance enforcement via flock: the kernel holds the lock for
-	// this process's life and releases it on ANY exit (clean, crash,
-	// kill -9), so there is never stale state to clean up. No pid file.
-	releaseLock, err := discovery.AcquireServerLock()
-	if err != nil {
-		log.Fatalf("%v", err)
+// cmdRepoRegister registers one repo. Fully-flagged invocation
+// (--name/--path plus --set for every required task repo key) never
+// prompts and produces the same repo entry as the interactive run.
+// With no flags, a TTY drives the interactive flow: discover runner
+// repos, huh searchable select, then prompts for name, path, and each
+// required key with the selected candidate's name/path as defaults.
+func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags, stdin io.Reader) int {
+	ctx := context.Background()
+	flagged := flagName != "" || flagPath != "" || len(sets) > 0
+
+	if flagged {
+		// Presence validation BEFORE any server contact.
+		if flagName == "" || flagPath == "" {
+			fmt.Fprintln(os.Stderr, "repo register: --name and --path are required for non-interactive registration")
+			return exitUsage
+		}
+		taskCfg := config.RawValues{}
+		for k, v := range sets {
+			if v == "" {
+				fmt.Fprintf(os.Stderr, "repo register: --set %s requires a non-empty value\n", k)
+				return exitUsage
+			}
+			taskCfg[k] = v
+		}
+		fields, err := c.RepoTaskFields(ctx)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		required := map[string]bool{}
+		for _, f := range fields {
+			required[f] = true
+		}
+		for k := range taskCfg {
+			if !required[k] {
+				fmt.Fprintf(os.Stderr, "repo register: unknown task key %q (required keys: %s)\n",
+					k, strings.Join(fields, ", "))
+				return exitUsage
+			}
+		}
+		var missing []string
+		for _, f := range fields {
+			if _, ok := taskCfg[f]; !ok {
+				missing = append(missing, f)
+			}
+		}
+		if len(missing) > 0 {
+			fmt.Fprintf(os.Stderr, "repo register: missing required task keys: %s (pass --set %s=<value>)\n",
+				strings.Join(missing, ", "), missing[0])
+			return exitUsage
+		}
+		info, err := c.RegisterRepo(ctx, repo.RegisterInput{Name: flagName, Path: flagPath, TaskConfig: taskCfg})
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		fmt.Println(info.Name)
+		return exitOK
 	}
-	defer releaseLock()
 
-	sockPath, err := discovery.SocketPath()
+	fields, err := c.RepoTaskFields(ctx)
 	if err != nil {
-		log.Fatalf("%v", err)
+		fmt.Fprintln(os.Stderr, err)
+		return exitFail
 	}
-	os.Remove(sockPath) // stale socket from a crashed server
-	ln, err := net.Listen("unix", sockPath)
-	if err != nil {
-		log.Fatalf("listen %s: %v", sockPath, err)
-	}
-	defer os.Remove(sockPath)
-
-	srv := server.New(*dryRun, server.ProdDeps(*dryRun))
-	log.Printf("relay-flow serve: socket=%s dry-run=%v", sockPath, *dryRun)
-
-	sig := make(chan os.Signal, 1)
-	signal.Notify(sig, syscall.SIGINT, syscall.SIGTERM)
-	go func() {
-		<-sig
-		log.Printf("shutting down")
-		srv.Shutdown()
-	}()
-	if err := srv.Serve(ln); err != nil {
-		log.Fatalf("serve: %v", err)
-	}
-}
-
-// cmdReport is invoked by the opencode plugin once per session.idle.
-// Thin socket client: the server resolves the outcome edge and calls the
-// tasks adapter — no config load, no tracker calls, no fallback. The
-// agent terminal is deliberately NOT closed here: it stays alive for
-// bounce nudges; only closeOn nodes close terminals.
-func cmdReport(args []string) {
-	fs := flag.NewFlagSet("report", flag.ExitOnError)
-	workflow := fs.String("workflow", "", "workflow name")
-	ticket := fs.String("ticket", "", "ticket key")
-	node := fs.String("node", "", "node name")
-	outcome := fs.String("outcome", "", "success or failure")
-	summary := fs.String("summary", "", "agent's summary of what it did")
-	fs.Parse(args)
-	if *workflow == "" || *ticket == "" || *node == "" || *outcome == "" || *summary == "" {
-		log.Fatalf("usage: relay-flow report --workflow <name> --ticket <key> --node <node> --outcome <success|failure> --summary <text>")
-	}
-	client, err := server.NewClient()
-	if err != nil {
-		log.Fatalf("%v", err)
+
+	if !isTTY(stdin) {
+		fmt.Fprintln(os.Stderr, "repo register: interactive registration requires a TTY (or pass --name/--path/--set)")
+		return exitFail
 	}
-	result, err := client.Report(*workflow, *ticket, *node, *outcome, *summary)
+	candidates, err := c.DiscoverRepos(ctx)
 	if err != nil {
-		log.Fatalf("report %s: %v", *ticket, err)
+		fmt.Fprintln(os.Stderr, err)
+		return exitFail
+	}
+	if len(candidates) == 0 {
+		fmt.Fprintln(os.Stderr, "repo register: runner discovered no repos")
+		return exitFail
 	}
-	// JSON on stdout (log goes to stderr) so the plugin can parse it.
-	out, _ := json.Marshal(map[string]string{"action": result.Action, "detail": result.Detail})
-	fmt.Println(string(out))
-	log.Printf("report %s: workflow=%s node=%s action=%s detail=%q", *ticket, *workflow, *node, result.Action, result.Detail)
-}
 
-// cmdSubmit reads a workflow YAML and sends it to the running server. cwd
-// must be inside the repo the workflow governs (repo resolved client-side).
-// The workflow's identity is the `name` field inside the YAML.
-func cmdSubmit(args []string) {
-	fs := flag.NewFlagSet("submit", flag.ExitOnError)
-	file := fs.String("f", "", "path to workflow YAML (default .workflow/workflow.yaml)")
-	fs.Parse(args)
-	if fs.NArg() != 0 {
-		log.Fatalf("usage: relay-flow submit [-f <yaml>]  (workflow name comes from the YAML's `name` field)")
+	// Searchable select over discovered candidates.
+	selected := 0
+	options := make([]huh.Option[int], len(candidates))
+	for i, cand := range candidates {
+		options[i] = huh.NewOption(cand.Name+"  ("+cand.Path+")", i)
 	}
-	path := *file
-	if path == "" {
-		path = filepath.Join(".workflow", "workflow.yaml")
+	pick := huh.NewForm(huh.NewGroup(huh.NewSelect[int]().
+		Title("Repository").
+		Options(options...).
+		Filtering(true).
+		Value(&selected)))
+	if err := pick.Run(); err != nil {
+		fmt.Fprintln(os.Stderr, "repo register: "+err.Error())
+		return exitFail
 	}
-	yamlBytes, err := os.ReadFile(path)
-	if err != nil {
-		log.Fatalf("read %s: %v", path, err)
+
+	// Name/path inputs default to the SELECTED candidate, then one input
+	// per required task repo key. Values pass through as entered; the
+	// service validates required keys.
+	cand := candidates[selected]
+	name := cand.Name
+	path := cand.Path
+	inputs := []huh.Field{
+		huh.NewInput().Title("Name").Value(&name),
+		huh.NewInput().Title("Path").Value(&path),
 	}
-	cwd, err := os.Getwd()
-	if err != nil {
-		log.Fatalf("%v", err)
+	values := make([]string, len(fields))
+	for i, f := range fields {
+		inputs = append(inputs, huh.NewInput().Title(f).Value(&values[i]))
+	}
+	if err := huh.NewForm(huh.NewGroup(inputs...)).Run(); err != nil {
+		fmt.Fprintln(os.Stderr, "repo register: "+err.Error())
+		return exitFail
 	}
-	client, err := server.NewClient()
+	taskCfg := config.RawValues{}
+	for i, f := range fields {
+		taskCfg[f] = values[i]
+	}
+	info, err := c.RegisterRepo(ctx, repo.RegisterInput{
+		Name:       name,
+		Path:       path,
+		TaskConfig: taskCfg,
+	})
 	if err != nil {
-		log.Fatalf("%v", err)
+		fmt.Fprintln(os.Stderr, err)
+		return exitFail
+	}
+	fmt.Println(info.Name)
+	return exitOK
+}
+
+// kvFlags collects repeated key=value flags (registration task config).
+// Parse rejects malformed pairs, empty keys/values, and duplicates.
+type kvFlags map[string]string
+
+func (k kvFlags) String() string { return "" }
+func (k kvFlags) Set(s string) error {
+	kv := strings.SplitN(s, "=", 2)
+	if len(kv) != 2 || kv[0] == "" || kv[1] == "" {
+		return fmt.Errorf("expected key=value with non-empty key and value, got %q", s)
+	}
+	if _, dup := k[kv[0]]; dup {
+		return fmt.Errorf("duplicate --set for key %q", kv[0])
+	}
+	k[kv[0]] = kv[1]
+	return nil
+}
+
+// --- run ---
+
+func cmdRun(c *server.Client, args []string) int {
+	if len(args) == 0 {
+		usage(os.Stderr)
+		return exitUsage
+	}
+	switch args[0] {
+	case "list":
+		fs := flag.NewFlagSet("run list", flag.ContinueOnError)
+		repoName := fs.String("repo", "", "filter by repo")
+		workflowName := fs.String("workflow", "", "filter by workflow")
+		ticket := fs.String("ticket", "", "filter by ticket")
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		runs, err := c.ListRuns(context.Background(), runsvc.Filter{
+			Repo:     *repoName,
+			Workflow: *workflowName,
+			Ticket:   *ticket,
+		})
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		for _, r := range runs {
+			fmt.Println(formatRunListRow(r))
+		}
+		return exitOK
+	case "get":
+		fs := flag.NewFlagSet("run get", flag.ContinueOnError)
+		ticket := fs.String("ticket", "", "ticket key")
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		if *ticket == "" {
+			fmt.Fprintln(os.Stderr, "run get: --ticket is required")
+			return exitUsage
+		}
+		rn, err := c.GetRunByTicket(context.Background(), *ticket)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		enc := json.NewEncoder(os.Stdout)
+		enc.SetIndent("", "  ")
+		_ = enc.Encode(rn)
+		return exitOK
+	case "cancel":
+		fs := flag.NewFlagSet("run cancel", flag.ContinueOnError)
+		ticket := fs.String("ticket", "", "ticket key")
+		reason := fs.String("reason", "", "cancel reason")
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		if *ticket == "" {
+			fmt.Fprintln(os.Stderr, "run cancel: --ticket is required")
+			return exitUsage
+		}
+		if err := c.CancelRun(context.Background(), *ticket, *reason); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		return exitOK
 	}
-	if err := client.Submit(cwd, yamlBytes); err != nil {
-		log.Fatalf("submit: %v", err)
+	usage(os.Stderr)
+	return exitUsage
+}
+
+func formatRunListRow(r runsvc.Run) string {
+	row := fmt.Sprintf("%s\t%s\t%s\t%s", r.ID, r.Ticket.Key, r.Workflow, r.State)
+	if r.Retry != nil {
+		row += fmt.Sprintf("\tretrying attempt=%d next=%s error=%q",
+			r.Retry.Attempt, r.Retry.NextRetryAt.Format(time.RFC3339), r.Retry.LastError)
 	}
-	fmt.Println("submitted")
+	return row
 }