relay-flow 0.2.0-alpha → 0.2.2-alpha

package/cmd/relay-flow/commands_test.go

@@ -1,20 +1,30 @@
 package main
 
 import (
+	"bytes"
 	"context"
+	"database/sql"
 	"errors"
+	"fmt"
+	"io"
 	"net"
 	"net/http"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"strings"
+	"sync"
+	"syscall"
 	"testing"
 	"time"
 
+	"github.com/charmbracelet/huh"
+	"github.com/rajpopat27/relay-flow/internal/config"
 	"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"
 	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
@@ -33,7 +43,7 @@ func cli(t *testing.T, home string, stdin string, args ...string) (code int) {
 func TestCommandSurfaceExists(t *testing.T) {
 	home := t.TempDir()
 	commands := [][]string{
-		{"init"}, {"serve", "--recover"}, {"stop"}, {"report"},
+		{"init"}, {"task", "auth"}, {"serve", "--recover"}, {"stop"}, {"report"},
 		{"workflow", "submit", "--file", "x.yaml"}, {"workflow", "remove", "--name", "x"},
 		{"workflow", "list"}, {"workflow", "get", "--name", "x"},
 		{"repo", "register"}, {"repo", "remove", "--name", "x"}, {"repo", "list"}, {"repo", "get", "--name", "x"},
@@ -92,11 +102,69 @@ func TestRunListRowShowsLifecycleAndActiveRetry(t *testing.T) {
 // without them per 5.5).
 func initHome(t *testing.T, home string) {
 	t.Helper()
-	if code := cli(t, home, "jira\norca\nopencode\n", "init"); code != 0 {
+	if code := cli(t, home, "", initArgs()...); code != 0 {
 		t.Fatalf("init exit = %d, want 0", code)
 	}
 }
 
+func initArgs() []string {
+	return []string{"init", "--task-plugin", "jira", "--runner-plugin", "orca", "--harness-plugin", "opencode"}
+}
+
+func initInput() string {
+	return "jira\norca\nopencode\n"
+}
+
+const authTestPlugin = "auth-dispatch-test"
+
+var (
+	registerAuthTestPlugin sync.Once
+	authTestArgs           []string
+	authTestInput          string
+)
+
+func ensureAuthTestPlugin() {
+	registerAuthTestPlugin.Do(func() {
+		task.Register(authTestPlugin, task.Factory{
+			RequiredRepoKeys: func() []string { return nil },
+			TaskScopeKey:     func(_, _ config.RawValues) (string, error) { return "auth-test", nil },
+			Auth: func(_ context.Context, args []string, stdin io.Reader) error {
+				authTestArgs = append([]string(nil), args...)
+				body, err := io.ReadAll(stdin)
+				if err != nil {
+					return err
+				}
+				authTestInput = string(body)
+				return nil
+			},
+			New: func(context.Context, task.RepoSpec) (task.System, error) { return nil, nil },
+		})
+	})
+}
+
+func TestTaskAuthDispatchesSelectedPlugin(t *testing.T) {
+	ensureAuthTestPlugin()
+	home := t.TempDir()
+	root := filepath.Join(home, ".relay-flow")
+	if err := os.MkdirAll(root, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := config.SaveMachine(filepath.Join(root, "config.yaml"), &config.Machine{TaskPlugin: authTestPlugin}); err != nil {
+		t.Fatal(err)
+	}
+	authTestArgs = nil
+	authTestInput = ""
+	if code := cli(t, home, "plugin-owned-input", "task", "auth", "--custom", "value"); code != 0 {
+		t.Fatalf("task auth exit = %d, want 0", code)
+	}
+	if got := strings.Join(authTestArgs, " "); got != "--custom value" {
+		t.Fatalf("plugin args = %q", got)
+	}
+	if authTestInput != "plugin-owned-input" {
+		t.Fatalf("plugin stdin = %q", authTestInput)
+	}
+}
+
 // 3.29 (lock): serve creates server.lock owner-only. Asserted through the
 // serve fixture.
 func TestServerLockIsOwnerOnly(t *testing.T) {
@@ -193,7 +261,7 @@ func TestReportUnreachableServerExits1(t *testing.T) {
 func TestInitRefusesToOverwrite(t *testing.T) {
 	home := t.TempDir()
 	// init reads the three plugin selections from stdin.
-	if code := cli(t, home, "jira\norca\nopencode\n", "init"); code != 0 {
+	if code := cli(t, home, initInput(), "init"); code != 0 {
 		t.Fatalf("first init exit = %d, want 0", code)
 	}
 	cfgPath := filepath.Join(home, ".relay-flow", "config.yaml")
@@ -214,7 +282,7 @@ func TestInitRefusesToOverwrite(t *testing.T) {
 		t.Fatalf("state.db is not a SQLite database (missing magic header); got %q", dbBefore[:min(16, len(dbBefore))])
 	}
 
-	if code := cli(t, home, "jira\norca\nopencode\n", "init"); code == 0 {
+	if code := cli(t, home, initInput(), "init"); code == 0 {
 		t.Fatal("init overwrote existing config/history")
 	}
 	if readFile(t, cfgPath) != cfg {
@@ -225,19 +293,266 @@ func TestInitRefusesToOverwrite(t *testing.T) {
 	}
 }
 
+func TestInitSelectionTitlesAndSingletons(t *testing.T) {
+	for _, tc := range []struct {
+		title string
+		value string
+	}{
+		{"Select task system", "jira"},
+		{"Select runner", "orca"},
+		{"Select harness", "opencode"},
+	} {
+		var selected string
+		field, err := pluginSelectField(tc.title, []string{tc.value}, &selected)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if field == nil {
+			t.Fatalf("%s singleton field is nil", tc.title)
+		}
+		var singletonOut bytes.Buffer
+		if err := field.RunAccessible(&singletonOut, strings.NewReader("1\n")); err != nil {
+			t.Fatal(err)
+		}
+		if selected != tc.value || !strings.Contains(singletonOut.String(), tc.title) {
+			t.Fatalf("%s singleton selection = %q, output %q", tc.title, selected, singletonOut.String())
+		}
+
+		field, err = pluginSelectField(tc.title, []string{tc.value, "other"}, &selected)
+		if err != nil {
+			t.Fatal(err)
+		}
+		var out bytes.Buffer
+		if err := field.RunAccessible(&out, strings.NewReader("1\n")); err != nil {
+			t.Fatal(err)
+		}
+		if !strings.Contains(out.String(), tc.title) {
+			t.Fatalf("selection output %q missing title %q", out.String(), tc.title)
+		}
+	}
+}
+
+func TestInitPrintsSelectedValuesAndCompletion(t *testing.T) {
+	code, out := captureStdout(t, func() int {
+		return cli(t, t.TempDir(), "", initArgs()...)
+	})
+	if code != 0 {
+		t.Fatalf("init exit = %d", code)
+	}
+	for _, want := range []string{"Task system: jira", "Runner: orca", "Harness: opencode", "Relay-flow initialized"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("init output %q missing %q", out, want)
+		}
+	}
+}
+
+func TestInitWritesHarnessPromptDefaults(t *testing.T) {
+	home := t.TempDir()
+	if code := cli(t, home, "", initArgs()...); code != 0 {
+		t.Fatalf("init exit = %d", code)
+	}
+	cfg, err := config.LoadMachine(filepath.Join(home, ".relay-flow", "config.yaml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, key := range []string{"initial", "feedback", "hitl"} {
+		value, ok := cfg.HarnessConfig[key].(string)
+		if !ok || value == "" {
+			t.Fatalf("harnessConfig.%s = %#v", key, cfg.HarnessConfig[key])
+		}
+	}
+}
+
+func TestInitWritesTaskTextDefaults(t *testing.T) {
+	home := t.TempDir()
+	if code := cli(t, home, "", initArgs()...); code != 0 {
+		t.Fatalf("init exit = %d", code)
+	}
+	cfg, err := config.LoadMachine(filepath.Join(home, ".relay-flow", "config.yaml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	templates, ok := rawValuesMap(cfg.TaskConfig["templates"])
+	if !ok {
+		t.Fatalf("taskConfig.templates = %#v", cfg.TaskConfig["templates"])
+	}
+	for _, key := range []string{"mailboxDescription", "summaryComment", "feedbackComment"} {
+		if value, ok := templates[key].(string); !ok || value == "" {
+			t.Fatalf("taskConfig.templates.%s = %#v", key, templates[key])
+		}
+	}
+}
+
+func TestInitDoesNotCollectOrWriteTaskCredentials(t *testing.T) {
+	home := t.TempDir()
+	if code := cli(t, home, "", initArgs()...); code != 0 {
+		t.Fatalf("init exit = %d", code)
+	}
+	root := filepath.Join(home, ".relay-flow")
+	configText := readFile(t, filepath.Join(root, "config.yaml"))
+	if strings.Contains(configText, "jira-site") || strings.Contains(configText, "email") || strings.Contains(configText, "token") {
+		t.Fatalf("normal config contains task credentials: %s", configText)
+	}
+	if _, err := os.Stat(filepath.Join(root, "credentials.yaml")); !os.IsNotExist(err) {
+		t.Fatalf("init wrote credentials.yaml: %v", err)
+	}
+}
+
+func TestInitForceRejectsRunningServerAndNonterminalRun(t *testing.T) {
+	t.Run("server running", func(t *testing.T) {
+		home := t.TempDir()
+		initHome(t, home)
+		lockPath := filepath.Join(home, ".relay-flow", "server.lock")
+		lock, err := os.OpenFile(lockPath, os.O_CREATE|os.O_RDWR, 0600)
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer lock.Close()
+		if err := syscall.Flock(int(lock.Fd()), syscall.LOCK_EX|syscall.LOCK_NB); err != nil {
+			t.Fatal(err)
+		}
+		defer syscall.Flock(int(lock.Fd()), syscall.LOCK_UN)
+		if code := cli(t, home, "", "init", "--force",
+			"--task-plugin", "jira", "--runner-plugin", "orca", "--harness-plugin", "opencode"); code != 1 {
+			t.Fatalf("forced init with server lock exit = %d, want 1", code)
+		}
+	})
+
+	t.Run("nonterminal run", func(t *testing.T) {
+		home := t.TempDir()
+		initHome(t, home)
+		root := filepath.Join(home, ".relay-flow")
+		insertRun(t, filepath.Join(root, "state.db"), "active", "starting")
+		configBefore := readFile(t, filepath.Join(root, "config.yaml"))
+		if code := cli(t, home, "", "init", "--force",
+			"--task-plugin", "jira", "--runner-plugin", "orca", "--harness-plugin", "opencode"); code != 1 {
+			t.Fatalf("forced init with active run exit = %d, want 1", code)
+		}
+		if got := readFile(t, filepath.Join(root, "config.yaml")); got != configBefore {
+			t.Fatal("rejected forced init changed config")
+		}
+	})
+}
+
+func TestInitForcePreservesDurableAndUserState(t *testing.T) {
+	home := t.TempDir()
+	initHome(t, home)
+	root := filepath.Join(home, ".relay-flow")
+	dbPath := filepath.Join(root, "state.db")
+	insertRun(t, dbPath, "completed", "completed")
+	dbBefore, err := os.Stat(dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	cfg, err := config.LoadMachine(filepath.Join(root, "config.yaml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	cfg.Repos = map[string]config.Repo{"existing": {Path: "/srv/existing"}}
+	cfg.HarnessConfig["initial"] = "custom {{ticket}}"
+	taskTemplates, ok := rawValuesMap(cfg.TaskConfig["templates"])
+	if !ok {
+		t.Fatalf("taskConfig.templates = %#v", cfg.TaskConfig["templates"])
+	}
+	taskTemplates["mailboxDescription"] = "custom {{nodeDescription}}"
+	if err := config.SaveMachine(filepath.Join(root, "config.yaml"), cfg); err != nil {
+		t.Fatal(err)
+	}
+	workflowDir := filepath.Join(root, "workflows")
+	if err := os.MkdirAll(workflowDir, 0700); err != nil {
+		t.Fatal(err)
+	}
+	workflowPath := filepath.Join(workflowDir, "saved.yaml")
+	logPath := filepath.Join(root, "server.log")
+	if err := os.WriteFile(workflowPath, []byte("saved workflow\n"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(logPath, []byte("saved log\n"), 0600); err != nil {
+		t.Fatal(err)
+	}
+
+	args := append([]string{"init", "--force"}, initArgs()[1:]...)
+	if code := cli(t, home, "", args...); code != 0 {
+		t.Fatalf("forced init exit = %d, want 0", code)
+	}
+	if got := readFile(t, workflowPath); got != "saved workflow\n" {
+		t.Fatalf("workflow changed: %q", got)
+	}
+	if got := readFile(t, logPath); got != "saved log\n" {
+		t.Fatalf("log changed: %q", got)
+	}
+	dbAfter, err := os.Stat(dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !os.SameFile(dbBefore, dbAfter) {
+		t.Fatal("forced init recreated state.db")
+	}
+	cfg, err = config.LoadMachine(filepath.Join(root, "config.yaml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := cfg.Repos["existing"]; !ok {
+		t.Fatal("forced init removed existing repo config")
+	}
+	if got := cfg.HarnessConfig["initial"]; got != "custom {{ticket}}" {
+		t.Fatalf("forced init changed prompt override: %#v", got)
+	}
+	gotTaskTemplates, ok := rawValuesMap(cfg.TaskConfig["templates"])
+	if !ok {
+		t.Fatalf("taskConfig.templates = %#v", cfg.TaskConfig["templates"])
+	}
+	if got := gotTaskTemplates["mailboxDescription"]; got != "custom {{nodeDescription}}" {
+		t.Fatalf("forced init changed task text override: %#v", got)
+	}
+	for _, key := range []string{"summaryComment", "feedbackComment"} {
+		if got, ok := gotTaskTemplates[key].(string); !ok || got == "" {
+			t.Fatalf("forced init omitted task default %s: %#v", key, gotTaskTemplates[key])
+		}
+	}
+	for _, key := range []string{"feedback", "hitl"} {
+		if got, ok := cfg.HarnessConfig[key].(string); !ok || got == "" {
+			t.Fatalf("forced init omitted harness default %s: %#v", key, cfg.HarnessConfig[key])
+		}
+	}
+	db, err := sql.Open("sqlite", dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+	var state string
+	if err := db.QueryRow(`SELECT state FROM relay_runs WHERE id = 'completed'`).Scan(&state); err != nil {
+		t.Fatalf("completed history missing: %v", err)
+	}
+	if state != "completed" {
+		t.Fatalf("completed history state = %q", state)
+	}
+}
+
+func rawValuesMap(value any) (map[string]any, bool) {
+	switch values := value.(type) {
+	case map[string]any:
+		return values, true
+	case config.RawValues:
+		return map[string]any(values), true
+	default:
+		return nil, false
+	}
+}
+
 // 8.2: --task-plugin/--runner-plugin/--harness-plugin run init without any
 // prompt/stdin and write the same machine config as the stdin path.
 func TestInitFlagsNonInteractive(t *testing.T) {
 	home := t.TempDir()
 	// Flags fully replace stdin: empty stdin must still succeed.
-	if code := cli(t, home, "", "init",
-		"--task-plugin", "jira", "--runner-plugin", "orca", "--harness-plugin", "opencode"); code != 0 {
+	if code := cli(t, home, "", initArgs()...); code != 0 {
 		t.Fatalf("flagged init exit = %d, want 0", code)
 	}
 	cfgFlags := readFile(t, filepath.Join(home, ".relay-flow", "config.yaml"))
 
 	home2 := t.TempDir()
-	if code := cli(t, home2, "jira\norca\nopencode\n", "init"); code != 0 {
+	if code := cli(t, home2, initInput(), "init"); code != 0 {
 		t.Fatalf("stdin init exit = %d, want 0", code)
 	}
 	cfgStdin := readFile(t, filepath.Join(home2, ".relay-flow", "config.yaml"))
@@ -271,13 +586,57 @@ func min(a, b int) int {
 	return b
 }
 
+func captureStdout(t *testing.T, fn func() int) (int, string) {
+	t.Helper()
+	old := os.Stdout
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	os.Stdout = w
+	done := make(chan []byte, 1)
+	go func() {
+		b, _ := io.ReadAll(r)
+		done <- b
+	}()
+	code := fn()
+	_ = w.Close()
+	os.Stdout = old
+	out := <-done
+	_ = r.Close()
+	return code, string(out)
+}
+
+func insertRun(t *testing.T, path, id, state string) {
+	t.Helper()
+	db, err := sql.Open("sqlite", path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+	now := time.Now().UTC()
+	var finished any
+	if state == "completed" || state == "canceled" {
+		finished = now
+	}
+	_, err = db.Exec(`INSERT INTO relay_runs
+		(id, repo, workflow, ticket_id, ticket_key, state, started_at, updated_at, finished_at)
+		VALUES (?, 'repo', 'workflow', ?, ?, ?, ?, ?, ?)`, id, id, id, state, now, now, finished)
+	if err != nil {
+		t.Fatal(err)
+	}
+}
+
 // 8.4: fully-flagged repo register never prompts and produces the same
 // repo entry the interactive run would post.
 type registerServer struct {
-	ackServer // embed for the unreachable stubs
-	fields    []string
-	gotInput  *repo.RegisterInput
-	calls     int
+	ackServer  // embed for the unreachable stubs
+	fields     []string
+	gotInput   *repo.RegisterInput
+	gotInputs  []repo.RegisterInput
+	successful []repo.RegisterInput
+	failName   string
+	calls      int
 }
 
 func (s *registerServer) TaskFields(context.Context) ([]string, error) {
@@ -288,6 +647,11 @@ func (s *registerServer) RegisterRepo(_ context.Context, in repo.RegisterInput)
 	s.calls++
 	cp := in
 	s.gotInput = &cp
+	s.gotInputs = append(s.gotInputs, cp)
+	if in.Name == s.failName {
+		return repo.Info{}, errors.New("registration failed")
+	}
+	s.successful = append(s.successful, cp)
 	return repo.Info{Name: in.Name, Path: in.Path, TaskConfig: in.TaskConfig}, nil
 }
 
@@ -319,7 +683,7 @@ func TestRepoRegisterFlagsNonInteractive(t *testing.T) {
 	// Fully-flagged run: no stdin, no TTY — must not prompt.
 	code := cli(t, home, "", "repo", "register",
 		"--name", "payments", "--path", "/srv/payments",
-		"--set", "project=PAY", "--set", "component=core")
+		"--set", "project=PAY")
 	if code != 0 {
 		t.Fatalf("fully-flagged register exit = %d, want 0", code)
 	}
@@ -329,16 +693,16 @@ func TestRepoRegisterFlagsNonInteractive(t *testing.T) {
 	if deps.gotInput.Name != "payments" || deps.gotInput.Path != "/srv/payments" {
 		t.Fatalf("name/path = %q/%q", deps.gotInput.Name, deps.gotInput.Path)
 	}
-	if deps.gotInput.TaskConfig["project"] != "PAY" || deps.gotInput.TaskConfig["component"] != "core" {
+	if deps.gotInput.TaskConfig["project"] != "PAY" || deps.gotInput.TaskConfig["component"] != "payments" {
 		t.Fatalf("taskConfig = %v", deps.gotInput.TaskConfig)
 	}
 
-	// Missing a required key is a usage error; only the TaskFields lookup
+	// Missing project is a usage error; component is derived from --name.
 	// is allowed to hit the server (RegisterRepo must not be called).
 	home2 := t.TempDir()
 	deps2 := serveRegister(t, home2, []string{"project", "component"})
 	if code := cli(t, home2, "", "repo", "register",
-		"--name", "x", "--path", "/x", "--set", "project=PAY"); code != 2 {
+		"--name", "x", "--path", "/x"); code != 2 {
 		t.Fatalf("missing required key exit = %d, want 2", code)
 	}
 	if deps2.gotInput != nil {
@@ -388,6 +752,220 @@ func TestRepoRegisterFlagsNonInteractive(t *testing.T) {
 		"--set", "project=PAY", "--set", "bogus=v"); code != 2 {
 		t.Fatalf("unknown key exit = %d, want 2", code)
 	}
+
+	// Component can never be prompted or overridden.
+	home6 := t.TempDir()
+	deps6 := serveRegister(t, home6, []string{"project", "component"})
+	if code := cli(t, home6, "", "repo", "register",
+		"--name", "x", "--path", "/x",
+		"--set", "project=PAY", "--set", "component=override"); code != 2 {
+		t.Fatalf("component override exit = %d, want 2", code)
+	}
+	if deps6.gotInput != nil {
+		t.Fatal("component override reached RegisterRepo")
+	}
+}
+
+func TestRepoMultiSelectAndSharedJiraMapping(t *testing.T) {
+	selected := []int{0, 1}
+	field := repoMultiSelect([]huh.Option[int]{
+		huh.NewOption("payments", 0),
+		huh.NewOption("checkout", 1),
+	}, &selected)
+	var out bytes.Buffer
+	if err := field.RunAccessible(&out, strings.NewReader("0\n")); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(out.String(), "Select repositories") {
+		t.Fatalf("multi-select output %q missing title", out.String())
+	}
+	if fmt.Sprint(selected) != "[0 1]" {
+		t.Fatalf("selected = %v, want [0 1]", selected)
+	}
+	if got := registrationSharedFields([]string{"project", "component"}); fmt.Sprint(got) != "[project]" {
+		t.Fatalf("prompted fields = %v, want project only", got)
+	}
+
+	home := t.TempDir()
+	deps := serveRegister(t, home, []string{"project", "component"})
+	client := server.NewClient(filepath.Join(home, ".relay-flow", "server.sock"))
+	candidates := []runner.RepoCandidate{
+		{Name: "payments", Path: "/srv/payments"},
+		{Name: "checkout", Path: "/srv/checkout"},
+	}
+	if err := registerSelectedRepos(context.Background(), client, candidates, selected,
+		[]string{"project", "component"}, kvFlags{"project": "PAY"}); err != nil {
+		t.Fatal(err)
+	}
+	if len(deps.successful) != 2 {
+		t.Fatalf("registrations = %d, want 2", len(deps.successful))
+	}
+	for _, input := range deps.successful {
+		if input.TaskConfig["project"] != "PAY" || input.TaskConfig["component"] != input.Name {
+			t.Fatalf("registration %+v has task config %v", input, input.TaskConfig)
+		}
+	}
+}
+
+func TestRepoRegistrationPartialFailureKeepsPriorSuccess(t *testing.T) {
+	home := t.TempDir()
+	deps := serveRegister(t, home, []string{"project", "component"})
+	deps.failName = "checkout"
+	client := server.NewClient(filepath.Join(home, ".relay-flow", "server.sock"))
+	candidates := []runner.RepoCandidate{
+		{Name: "payments", Path: "/srv/payments"},
+		{Name: "checkout", Path: "/srv/checkout"},
+		{Name: "later", Path: "/srv/later"},
+	}
+	err := registerSelectedRepos(context.Background(), client, candidates, []int{0, 1, 2},
+		[]string{"project", "component"}, kvFlags{"project": "PAY"})
+	if err == nil || !strings.Contains(err.Error(), "checkout") {
+		t.Fatalf("partial failure = %v, want failed repo name", err)
+	}
+	if len(deps.successful) != 1 || deps.successful[0].Name != "payments" {
+		t.Fatalf("successful registrations = %+v, want payments preserved", deps.successful)
+	}
+	if len(deps.gotInputs) != 2 {
+		t.Fatalf("registration attempts = %d, want stop after failed second repo", len(deps.gotInputs))
+	}
+}
+
+func TestBackgroundServeReadinessAndStop(t *testing.T) {
+	home := t.TempDir()
+	root := filepath.Join(home, ".relay-flow")
+	t.Setenv("RELAY_FLOW_HOME", root)
+	if code := run(initArgs(), strings.NewReader("")); code != 0 {
+		t.Fatalf("init exit = %d", code)
+	}
+	binary := buildCLIBinary(t)
+	start := exec.Command(binary, "serve", "--background")
+	start.Env = os.Environ()
+	out, err := start.CombinedOutput()
+	if err != nil {
+		t.Fatalf("background serve: %v\n%s", err, out)
+	}
+	if !strings.Contains(string(out), "Relay-flow server started") {
+		t.Fatalf("background output = %q", out)
+	}
+	client := server.NewClient(filepath.Join(root, "server.sock"))
+	if _, err := client.ListRepos(context.Background()); err != nil {
+		t.Fatalf("ready server did not respond: %v", err)
+	}
+	stop := exec.Command(binary, "stop")
+	stop.Env = os.Environ()
+	if out, err := stop.CombinedOutput(); err != nil {
+		t.Fatalf("stop: %v\n%s", err, out)
+	}
+	waitForServerStop(t, client)
+}
+
+func TestBackgroundServeFailurePointsToLog(t *testing.T) {
+	home := t.TempDir()
+	root := filepath.Join(home, ".relay-flow")
+	t.Setenv("RELAY_FLOW_HOME", root)
+	if code := run(initArgs(), strings.NewReader("")); code != 0 {
+		t.Fatalf("init exit = %d", code)
+	}
+	if err := os.WriteFile(filepath.Join(root, "config.yaml"), []byte("invalid: true\n"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	binary := buildCLIBinary(t)
+	start := exec.Command(binary, "serve", "--background")
+	start.Env = os.Environ()
+	out, err := start.CombinedOutput()
+	if err == nil {
+		t.Fatalf("background serve unexpectedly succeeded: %s", out)
+	}
+	if !strings.Contains(string(out), "server.log") {
+		t.Fatalf("background failure %q does not point to server.log", out)
+	}
+	log := readFile(t, filepath.Join(root, "server.log"))
+	if !strings.Contains(log, "server startup failed") {
+		t.Fatalf("server.log missing startup error: %q", log)
+	}
+}
+
+func TestForegroundServeRemainsBlocking(t *testing.T) {
+	home := t.TempDir()
+	root := filepath.Join(home, ".relay-flow")
+	t.Setenv("RELAY_FLOW_HOME", root)
+	if code := run(initArgs(), strings.NewReader("")); code != 0 {
+		t.Fatalf("init exit = %d", code)
+	}
+	binary := buildCLIBinary(t)
+	serve := exec.Command(binary, "serve")
+	serve.Env = os.Environ()
+	if err := serve.Start(); err != nil {
+		t.Fatal(err)
+	}
+	wait := make(chan error, 1)
+	go func() { wait <- serve.Wait() }()
+	t.Cleanup(func() {
+		if serve.Process != nil {
+			_ = serve.Process.Kill()
+		}
+	})
+	client := server.NewClient(filepath.Join(root, "server.sock"))
+	waitForServer(t, client)
+	select {
+	case err := <-wait:
+		t.Fatalf("foreground serve returned before stop: %v", err)
+	case <-time.After(200 * time.Millisecond):
+	}
+	stop := exec.Command(binary, "stop")
+	stop.Env = os.Environ()
+	if out, err := stop.CombinedOutput(); err != nil {
+		t.Fatalf("stop: %v\n%s", err, out)
+	}
+	select {
+	case err := <-wait:
+		if err != nil {
+			t.Fatalf("foreground serve exit: %v", err)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("foreground serve did not exit after stop")
+	}
+}
+
+func buildCLIBinary(t *testing.T) string {
+	t.Helper()
+	binary := filepath.Join(t.TempDir(), "relay-flow")
+	cmd := exec.Command("go", "build", "-buildvcs=false", "-o", binary, ".")
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("build relay-flow: %v\n%s", err, out)
+	}
+	return binary
+}
+
+func waitForServer(t *testing.T, client *server.Client) {
+	t.Helper()
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) {
+		ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+		_, err := client.ListRepos(ctx)
+		cancel()
+		if err == nil {
+			return
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	t.Fatal("server did not become ready")
+}
+
+func waitForServerStop(t *testing.T, client *server.Client) {
+	t.Helper()
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) {
+		ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+		_, err := client.ListRepos(ctx)
+		cancel()
+		if err != nil {
+			return
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	t.Fatal("server remained reachable after stop")
 }
 
 var errReportInvalid = errors.New("invalid report")