relay-flow 0.3.8-alpha → 0.3.10-alpha

package/README.md

@@ -16,6 +16,10 @@ Install the latest released CLI with Homebrew:
 brew install rajpopat27/tap/relay-flow
 ```
 
+The package installs both equivalent commands, `relay-flow` and `rf`. The
+short `rf` name is also included in release archives and can be installed by
+`install.sh` or with `go install ./cmd/relay-flow ./cmd/rf` from a checkout.
+
 ### 2. Install the harness extension
 
 Choose the harness that will run your agent sessions. Both commands install the
@@ -24,13 +28,13 @@ same `relay-flow-plugin` package with host-specific entrypoints.
 **OpenCode**
 
 ```sh
-opencode plugin relay-flow-plugin@0.3.8-alpha
+opencode plugin relay-flow-plugin@0.3.10-alpha
 ```
 
 **Pi**
 
 ```sh
-pi install npm:relay-flow-plugin@0.3.8-alpha
+pi install npm:relay-flow-plugin@0.3.10-alpha
 ```
 
 Pi loads the package's `pi.ts` extension from its manifest. Do not add
@@ -62,7 +66,7 @@ relay-flow init \
   --runner-plugin orca \
   --harness-plugin opencode
 relay-flow task auth
-relay-flow serve --background
+rf serve
 ```
 
 For Beads, skip `task auth` and initialize/authenticate the Beads workspace
@@ -84,7 +88,7 @@ For Herdr, register the repository path directly; relay-flow creates ticket
 worktrees lazily. The interactive registration asks for the task-system values
 required by the selected task plugin. `repo register` remains the standalone
 escape hatch for adding repositories after initialization and requires a
-running `relay-flow serve --background`.
+running `rf serve` (or `relay-flow serve`).
 
 ### 5. Submit a workflow
 
@@ -160,7 +164,7 @@ OpenCode plugin configuration uses both entrypoints. The server entrypoint is li
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["relay-flow-plugin@0.3.8-alpha"]
+  "plugin": ["relay-flow-plugin@0.3.10-alpha"]
 }
 ```
 
@@ -169,7 +173,7 @@ The native HITL approval entrypoint is listed in `.opencode/tui.json`:
 ```json
 {
   "$schema": "https://opencode.ai/tui.json",
-  "plugin": ["relay-flow-plugin@0.3.8-alpha"]
+  "plugin": ["relay-flow-plugin@0.3.10-alpha"]
 }
 ```
 
@@ -185,7 +189,7 @@ Pi plugin: install the same published package manually in Pi's global package
 settings before starting a Pi harness session:
 
 ```sh
-pi install npm:relay-flow-plugin@0.3.8-alpha
+pi install npm:relay-flow-plugin@0.3.10-alpha
 ```
 
 Relay-flow does not install or configure the package automatically. Pi resolves
@@ -221,7 +225,7 @@ For scripts and existing installations, keep the independent sequence:
 ```sh
 relay-flow init --task-plugin jira --runner-plugin orca --harness-plugin opencode
 relay-flow task auth --site https://company.atlassian.net --email you@example.com --token "$JIRA_API_TOKEN"
-relay-flow serve --background
+rf serve
 ```
 
 `task auth` delegates to the selected task plug-in. Jira prompts for its site,
@@ -262,12 +266,11 @@ workflows/<name>.yaml 0644  submitted workflow definitions
 
 The guided first-run flow can start the server and open repository registration
 for you. `repo register` remains a server-backed standalone command for later
-additions: if no server is running, start it with
-`relay-flow serve --background` (or rerun interactive `relay-flow init` for a
-new home).
+additions: if no server is running, start it with `rf serve` (or rerun
+interactive `relay-flow init` for a new home).
 
 ```sh
-relay-flow serve --background
+rf serve
 ```
 
 The repo must already exist in the runner. For the Orca runner, add it first
@@ -402,13 +405,18 @@ Outside that flow, `repo register` and `workflow submit` require the server to
 already be running; the same process polls repos and drives runs.
 
 ```sh
-relay-flow serve              # normal start; requires an initialized database
-relay-flow serve --background # detached; returns after the server is ready
-relay-flow serve --recover    # explicit destructive rebuild from the task system
-relay-flow stop
-```
-
-`--background` preserves `--debug` and `--recover`, logs to `~/.relay-flow/server.log`, and remains stoppable with `relay-flow stop`. Plain `serve` remains foreground and blocking.
+rf serve                    # detached by default; waits for readiness
+relay-flow serve --foreground # blocking mode for supervisors and development
+relay-flow serve --background # compatibility spelling for detached startup
+rf serve --recover           # explicit destructive rebuild from the task system
+rf stop
+```
+
+Both executable names share the same home, socket, lock, database, logs, exit
+codes, and server lifecycle. Detached startup logs diagnostics to
+`~/.relay-flow/server.log` and does not inherit a temporary or deleted caller
+working directory. Use `--foreground` only when the process supervisor owns
+the server lifetime; `--background` remains accepted for existing scripts.
 
 `serve --recover` treats ALL SQLite execution state as gone, closes surviving run-owned terminals (preserving worktrees and code), resets Jira parent+mailbox state, and starts every labeled parent in a fresh deterministic run from `start` with fresh `nodeVisitID`s. Recovery never runs automatically; database loss is never inferred.
 

package/cmd/relay-flow/commands_test.go

@@ -12,6 +12,9 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"reflect"
+	"runtime"
+	"strconv"
 	"strings"
 	"sync"
 	"syscall"
@@ -43,11 +46,11 @@ func cli(t *testing.T, home string, stdin string, args ...string) (code int) {
 func TestCommandSurfaceExists(t *testing.T) {
 	home := t.TempDir()
 	commands := [][]string{
-		{"init"}, {"task", "auth"}, {"serve", "--recover"}, {"stop"}, {"report"},
+		{"init"}, {"task", "auth"}, {"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"},
-		{"run", "list"}, {"run", "get", "--ticket", "PAY-101"}, {"run", "restart", "--ticket", "PAY-101"}, {"run", "cancel", "--ticket", "PAY-101"},
+		{"run", "list"}, {"run", "get", "--ticket", "PAY-101"}, {"run", "restart", "--ticket", "PAY-101"}, {"run", "cancel", "--ticket", "PAY-101"}, {"run", "backfill-owner", "--repo", "payments", "--ticket", "PAY-101", "--workflow", "basicFlow"},
 	}
 	for _, argv := range commands {
 		// Recognized commands do not exit 2 ("usage/unknown"); they may exit
@@ -69,14 +72,15 @@ func TestUnknownFlagExits2(t *testing.T) {
 func TestRequiredFlagMissingExits2(t *testing.T) {
 	home := t.TempDir()
 	for _, argv := range [][]string{
-		{"workflow", "submit"}, // missing --file
-		{"workflow", "remove"}, // missing --name
-		{"workflow", "get"},    // missing --name
-		{"repo", "remove"},     // missing --name
-		{"repo", "get"},        // missing --name
-		{"run", "get"},         // missing --ticket
-		{"run", "restart"},     // missing --ticket
-		{"run", "cancel"},      // missing --ticket
+		{"workflow", "submit"},    // missing --file
+		{"workflow", "remove"},    // missing --name
+		{"workflow", "get"},       // missing --name
+		{"repo", "remove"},        // missing --name
+		{"repo", "get"},           // missing --name
+		{"run", "get"},            // missing --ticket
+		{"run", "restart"},        // missing --ticket
+		{"run", "cancel"},         // missing --ticket
+		{"run", "backfill-owner"}, // missing --repo/--ticket/--workflow
 	} {
 		if code := cli(t, home, "", argv...); code != 2 {
 			t.Fatalf("%v with missing required flag exit = %d, want 2", argv, code)
@@ -171,9 +175,19 @@ func TestTaskAuthDispatchesSelectedPlugin(t *testing.T) {
 func TestServerLockIsOwnerOnly(t *testing.T) {
 	home := t.TempDir()
 	initHome(t, home)
-	// Start serve in the background of the test via the parser entry; it
-	// creates the flock file then blocks. We assert the lock file's mode.
-	go cli(t, home, "", "serve")
+	// Start foreground serve in the background of the test via the parser
+	// entry; it creates the flock file then blocks. We assert the lock file's
+	// mode, then stop the fixture so the test does not leak a server.
+	done := make(chan int, 1)
+	go func() { done <- cli(t, home, "", "serve", "--foreground") }()
+	t.Cleanup(func() {
+		_ = cli(t, home, "", "stop")
+		select {
+		case <-done:
+		case <-time.After(5 * time.Second):
+			t.Errorf("foreground serve did not stop")
+		}
+	})
 	lock := filepath.Join(home, ".relay-flow", "server.lock")
 	var fi os.FileInfo
 	var err error
@@ -191,6 +205,7 @@ func TestServerLockIsOwnerOnly(t *testing.T) {
 	if fi.Mode().Perm() != 0600 {
 		t.Fatalf("server.lock mode = %o, want 0600", fi.Mode().Perm())
 	}
+	waitForServer(t, server.NewClient(filepath.Join(home, ".relay-flow", "server.sock")))
 }
 
 // 3.29 (socket): the serve startup path owns server.sock creation and chmods
@@ -199,7 +214,16 @@ func TestServerLockIsOwnerOnly(t *testing.T) {
 func TestServerSocketIsOwnerOnly(t *testing.T) {
 	home := t.TempDir()
 	initHome(t, home)
-	go cli(t, home, "", "serve")
+	done := make(chan int, 1)
+	go func() { done <- cli(t, home, "", "serve", "--foreground") }()
+	t.Cleanup(func() {
+		_ = cli(t, home, "", "stop")
+		select {
+		case <-done:
+		case <-time.After(5 * time.Second):
+			t.Errorf("foreground serve did not stop")
+		}
+	})
 	sock := filepath.Join(home, ".relay-flow", "server.sock")
 	var fi os.FileInfo
 	var err error
@@ -1009,7 +1033,239 @@ func TestRepoRegistrationPartialFailureKeepsPriorSuccess(t *testing.T) {
 	}
 }
 
+func TestDefaultServeReadinessAndStop(t *testing.T) {
+	testDetachedServe(t, nil)
+}
+
+func TestDefaultServeRelativeHomeUsesSharedState(t *testing.T) {
+	caller := t.TempDir()
+	relativeHome := ".rf-rel"
+	expectedRoot := filepath.Join(caller, relativeHome)
+	t.Setenv("RELAY_FLOW_HOME", relativeHome)
+	binary := buildCLIBinary(t)
+	t.Cleanup(func() {
+		stop := exec.Command(binary, "stop")
+		stop.Dir = caller
+		stop.Env = os.Environ()
+		_, _ = stop.CombinedOutput()
+	})
+
+	init := exec.Command(binary, initArgs()...)
+	init.Dir = caller
+	init.Env = os.Environ()
+	if out, err := init.CombinedOutput(); err != nil {
+		t.Fatalf("relative-home init: %v\n%s", err, out)
+	}
+	for _, name := range []string{"config.yaml", "state.db"} {
+		if _, err := os.Stat(filepath.Join(expectedRoot, name)); err != nil {
+			t.Fatalf("relative-home init missing %s: %v", name, err)
+		}
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	serve := exec.CommandContext(ctx, binary, "serve")
+	serve.Dir = caller
+	serve.Env = os.Environ()
+	out, err := serve.CombinedOutput()
+	if err != nil {
+		t.Fatalf("relative-home detached serve: %v\n%s", err, out)
+	}
+	client := server.NewClient(filepath.Join(expectedRoot, "server.sock"))
+	if _, err := client.ListRepos(context.Background()); err != nil {
+		t.Fatalf("relative-home server did not respond: %v", err)
+	}
+	stop := exec.Command(binary, "stop")
+	stop.Dir = caller
+	stop.Env = os.Environ()
+	if out, err := stop.CombinedOutput(); err != nil {
+		t.Fatalf("relative-home stop: %v\n%s", err, out)
+	}
+	waitForServerStop(t, client)
+}
+
+func TestInProcessDefaultServeReadinessAndStop(t *testing.T) {
+	home := t.TempDir()
+	initHome(t, home)
+	if code := cli(t, home, "", "serve"); code != exitOK {
+		t.Fatalf("in-process detached serve exit = %d", code)
+	}
+	client := server.NewClient(filepath.Join(home, ".relay-flow", "server.sock"))
+	if _, err := client.ListRepos(context.Background()); err != nil {
+		t.Fatalf("in-process detached server did not respond: %v", err)
+	}
+	if code := cli(t, home, "", "stop"); code != exitOK {
+		t.Fatalf("in-process detached stop exit = %d", code)
+	}
+	waitForServerStop(t, client)
+}
+
+func TestDetachedServeUsesStableWorkingDirectory(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)
+	t.Cleanup(func() {
+		stop := exec.Command(binary, "stop")
+		stop.Env = os.Environ()
+		_, _ = stop.CombinedOutput()
+	})
+	caller := t.TempDir()
+	serve := exec.Command(binary, "serve")
+	serve.Dir = caller
+	serve.Env = os.Environ()
+	out, err := serve.CombinedOutput()
+	if err != nil {
+		t.Fatalf("detached serve from temporary directory: %v\n%s", err, 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)
+	}
+	if err := os.RemoveAll(caller); err != nil {
+		t.Fatal(err)
+	}
+	cwd, ok, inspectErr := waitForServeProcessCWD(binary)
+	if inspectErr != nil {
+		t.Skipf("process cwd inspection unavailable: %v", inspectErr)
+	}
+	if !ok {
+		t.Fatalf("could not find detached serve process")
+	}
+	if cwd != root {
+		t.Fatalf("detached server cwd = %q, want stable root %q", cwd, root)
+	}
+	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 TestForegroundServeUsesStableWorkingDirectory(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)
+	caller := t.TempDir()
+	serve := exec.Command(binary, "serve", "--foreground")
+	serve.Dir = caller
+	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)
+	if err := os.RemoveAll(caller); err != nil {
+		t.Fatal(err)
+	}
+	cwd, ok, inspectErr := waitForServeProcessCWD(binary)
+	if inspectErr != nil {
+		t.Skipf("process cwd inspection unavailable: %v", inspectErr)
+	}
+	if !ok {
+		t.Fatalf("could not find foreground serve process")
+	}
+	if cwd != root {
+		t.Fatalf("foreground server cwd = %q, want stable root %q", cwd, root)
+	}
+	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 TestForegroundServeRelativeHomeUsesSharedState(t *testing.T) {
+	caller := t.TempDir()
+	relativeHome := ".rf-fg"
+	expectedRoot := filepath.Join(caller, relativeHome)
+	t.Setenv("RELAY_FLOW_HOME", relativeHome)
+	binary := buildCLIBinary(t)
+
+	init := exec.Command(binary, initArgs()...)
+	init.Dir = caller
+	init.Env = os.Environ()
+	if out, err := init.CombinedOutput(); err != nil {
+		t.Fatalf("relative-home init: %v\n%s", err, out)
+	}
+	serve := exec.Command(binary, "serve", "--foreground")
+	serve.Dir = caller
+	serve.Env = os.Environ()
+	var serveStdout, serveStderr bytes.Buffer
+	serve.Stdout = &serveStdout
+	serve.Stderr = &serveStderr
+	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(expectedRoot, "server.sock"))
+	if err := waitForServerResult(client, 15*time.Second); err != nil {
+		logData, _ := os.ReadFile(filepath.Join(expectedRoot, "server.log"))
+		t.Fatalf("relative-home foreground readiness: %v; stdout=%q stderr=%q server.log=%q", err, serveStdout.String(), serveStderr.String(), string(logData))
+	}
+	for _, name := range []string{"config.yaml", "state.db", "server.sock", "server.lock"} {
+		if _, err := os.Stat(filepath.Join(expectedRoot, name)); err != nil {
+			t.Fatalf("relative-home foreground missing %s: %v", name, err)
+		}
+	}
+	cwd, ok, inspectErr := waitForServeProcessCWD(binary)
+	if inspectErr != nil {
+		t.Skipf("process cwd inspection unavailable: %v", inspectErr)
+	}
+	if !ok || cwd != expectedRoot {
+		t.Fatalf("relative-home foreground cwd = %q (found=%v), want %q", cwd, ok, expectedRoot)
+	}
+	stop := exec.Command(binary, "stop")
+	stop.Dir = caller
+	stop.Env = os.Environ()
+	if out, err := stop.CombinedOutput(); err != nil {
+		t.Fatalf("relative-home foreground stop: %v\n%s", err, out)
+	}
+	select {
+	case err := <-wait:
+		if err != nil {
+			t.Fatalf("relative-home foreground serve exit: %v", err)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("relative-home foreground serve did not exit after stop")
+	}
+}
+
 func TestBackgroundServeReadinessAndStop(t *testing.T) {
+	testDetachedServe(t, []string{"--background"})
+}
+
+func testDetachedServe(t *testing.T, mode []string) {
+	t.Helper()
 	home := t.TempDir()
 	root := filepath.Join(home, ".relay-flow")
 	t.Setenv("RELAY_FLOW_HOME", root)
@@ -1017,14 +1273,15 @@ func TestBackgroundServeReadinessAndStop(t *testing.T) {
 		t.Fatalf("init exit = %d", code)
 	}
 	binary := buildCLIBinary(t)
-	start := exec.Command(binary, "serve", "--background")
+	args := append([]string{"serve"}, mode...)
+	start := exec.Command(binary, args...)
 	start.Env = os.Environ()
 	out, err := start.CombinedOutput()
 	if err != nil {
-		t.Fatalf("background serve: %v\n%s", err, out)
+		t.Fatalf("detached serve: %v\n%s", err, out)
 	}
 	if !strings.Contains(string(out), "Relay-flow server started") {
-		t.Fatalf("background output = %q", out)
+		t.Fatalf("detached output = %q", out)
 	}
 	client := server.NewClient(filepath.Join(root, "server.sock"))
 	if _, err := client.ListRepos(context.Background()); err != nil {
@@ -1038,6 +1295,29 @@ func TestBackgroundServeReadinessAndStop(t *testing.T) {
 	waitForServerStop(t, client)
 }
 
+func TestServeRejectsConflictingModes(t *testing.T) {
+	if code := cli(t, t.TempDir(), "", "serve", "--foreground", "--background"); code != exitUsage {
+		t.Fatalf("conflicting serve modes exit = %d, want %d", code, exitUsage)
+	}
+}
+
+func TestServeChildArgsPropagateOnlyRecoveryAndDebug(t *testing.T) {
+	for _, tc := range []struct {
+		recover bool
+		debug   bool
+		want    []string
+	}{
+		{want: []string{"serve"}},
+		{recover: true, want: []string{"serve", "--recover"}},
+		{debug: true, want: []string{"serve", "--debug"}},
+		{recover: true, debug: true, want: []string{"serve", "--recover", "--debug"}},
+	} {
+		if got := serveChildArgs(tc.recover, tc.debug); !reflect.DeepEqual(got, tc.want) {
+			t.Fatalf("serveChildArgs(%v, %v) = %v, want %v", tc.recover, tc.debug, got, tc.want)
+		}
+	}
+}
+
 func TestBackgroundServeFailurePointsToLog(t *testing.T) {
 	home := t.TempDir()
 	root := filepath.Join(home, ".relay-flow")
@@ -1064,6 +1344,33 @@ func TestBackgroundServeFailurePointsToLog(t *testing.T) {
 	}
 }
 
+func TestAnchorForegroundServeNormalizesHomeEnvironment(t *testing.T) {
+	originalWD, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	originalPWD, hadPWD := os.LookupEnv("PWD")
+	defer func() {
+		_ = os.Chdir(originalWD)
+		if hadPWD {
+			_ = os.Setenv("PWD", originalPWD)
+		} else {
+			_ = os.Unsetenv("PWD")
+		}
+	}()
+	root := filepath.Join(t.TempDir(), "stable-home")
+	t.Setenv("RELAY_FLOW_HOME", "relative-home")
+	if err := anchorForegroundServe(root); err != nil {
+		t.Fatal(err)
+	}
+	if got := os.Getenv("RELAY_FLOW_HOME"); got != root {
+		t.Fatalf("RELAY_FLOW_HOME = %q, want %q", got, root)
+	}
+	if got, err := os.Getwd(); err != nil || got != root {
+		t.Fatalf("working directory = %q, %v; want %q", got, err, root)
+	}
+}
+
 func TestForegroundServeRemainsBlocking(t *testing.T) {
 	home := t.TempDir()
 	root := filepath.Join(home, ".relay-flow")
@@ -1072,7 +1379,7 @@ func TestForegroundServeRemainsBlocking(t *testing.T) {
 		t.Fatalf("init exit = %d", code)
 	}
 	binary := buildCLIBinary(t)
-	serve := exec.Command(binary, "serve")
+	serve := exec.Command(binary, "serve", "--foreground")
 	serve.Env = os.Environ()
 	if err := serve.Start(); err != nil {
 		t.Fatal(err)
@@ -1106,6 +1413,104 @@ func TestForegroundServeRemainsBlocking(t *testing.T) {
 	}
 }
 
+func waitForServeProcessCWD(executable string) (string, bool, error) {
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) {
+		pids, err := serveProcessIDs(executable)
+		if err != nil {
+			return "", false, err
+		}
+		for _, pid := range pids {
+			cwd, readErr := processCWD(pid)
+			if readErr == nil {
+				return cwd, true, nil
+			}
+			if runtime.GOOS == "darwin" {
+				return "", false, readErr
+			}
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	return "", false, nil
+}
+
+func serveProcessIDs(executable string) ([]int, error) {
+	switch runtime.GOOS {
+	case "linux":
+		entries, err := os.ReadDir("/proc")
+		if err != nil {
+			return nil, fmt.Errorf("read /proc: %w", err)
+		}
+		var pids []int
+		for _, entry := range entries {
+			if !entry.IsDir() || entry.Name() == "self" {
+				continue
+			}
+			cmdline, readErr := os.ReadFile(filepath.Join("/proc", entry.Name(), "cmdline"))
+			if readErr != nil {
+				continue
+			}
+			args := strings.Split(strings.TrimRight(string(cmdline), "\x00"), "\x00")
+			if len(args) < 2 || args[0] != executable || args[1] != "serve" {
+				continue
+			}
+			pid, parseErr := strconv.Atoi(entry.Name())
+			if parseErr == nil {
+				pids = append(pids, pid)
+			}
+		}
+		return pids, nil
+	case "darwin":
+		output, err := exec.Command("ps", "-axo", "pid=,command=").Output()
+		if err != nil {
+			return nil, fmt.Errorf("list processes with ps: %w", err)
+		}
+		var pids []int
+		for _, line := range strings.Split(string(output), "\n") {
+			line = strings.TrimSpace(line)
+			fields := strings.Fields(line)
+			if len(fields) < 2 {
+				continue
+			}
+			pid, parseErr := strconv.Atoi(fields[0])
+			if parseErr != nil {
+				continue
+			}
+			command := strings.TrimSpace(strings.TrimPrefix(line, fields[0]))
+			if strings.HasPrefix(command, executable+" serve") {
+				pids = append(pids, pid)
+			}
+		}
+		return pids, nil
+	default:
+		return nil, fmt.Errorf("process cwd inspection is unsupported on %s", runtime.GOOS)
+	}
+}
+
+func processCWD(pid int) (string, error) {
+	switch runtime.GOOS {
+	case "linux":
+		return os.Readlink(filepath.Join("/proc", strconv.Itoa(pid), "cwd"))
+	case "darwin":
+		lsof, err := exec.LookPath("lsof")
+		if err != nil {
+			return "", fmt.Errorf("find lsof for Darwin cwd inspection: %w", err)
+		}
+		output, err := exec.Command(lsof, "-a", "-p", strconv.Itoa(pid), "-d", "cwd", "-Fn").Output()
+		if err != nil {
+			return "", fmt.Errorf("inspect cwd with lsof: %w", err)
+		}
+		for _, line := range strings.Split(string(output), "\n") {
+			if strings.HasPrefix(line, "n") {
+				return strings.TrimPrefix(line, "n"), nil
+			}
+		}
+		return "", fmt.Errorf("lsof returned no cwd for pid %d", pid)
+	default:
+		return "", fmt.Errorf("process cwd inspection is unsupported on %s", runtime.GOOS)
+	}
+}
+
 func buildCLIBinary(t *testing.T) string {
 	t.Helper()
 	binary := filepath.Join(t.TempDir(), "relay-flow")
@@ -1119,17 +1524,28 @@ func buildCLIBinary(t *testing.T) string {
 
 func waitForServer(t *testing.T, client *server.Client) {
 	t.Helper()
-	deadline := time.Now().Add(5 * time.Second)
+	waitForServerTimeout(t, client, 5*time.Second)
+}
+
+func waitForServerTimeout(t *testing.T, client *server.Client, timeout time.Duration) {
+	t.Helper()
+	if err := waitForServerResult(client, timeout); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func waitForServerResult(client *server.Client, timeout time.Duration) error {
+	deadline := time.Now().Add(timeout)
 	for time.Now().Before(deadline) {
 		ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
 		_, err := client.ListRepos(ctx)
 		cancel()
 		if err == nil {
-			return
+			return nil
 		}
 		time.Sleep(20 * time.Millisecond)
 	}
-	t.Fatal("server did not become ready")
+	return fmt.Errorf("server did not become ready")
 }
 
 func waitForServerStop(t *testing.T, client *server.Client) {
@@ -1187,6 +1603,9 @@ func (s *ackServer) RestartRun(context.Context, string) (runsvc.Run, error) {
 	panic("unreachable")
 }
 func (s *ackServer) CancelRun(context.Context, string, string) error { panic("unreachable") }
+func (s *ackServer) BackfillClaimOwner(context.Context, string, string, string) error {
+	panic("unreachable")
+}
 func (s *ackServer) DiscoverRepos(context.Context) ([]runner.RepoCandidate, error) {
 	panic("unreachable")
 }