relay-flow 0.2.8-alpha → 0.2.9-alpha

package/cmd/relay-flow/main.go

@@ -136,6 +136,7 @@ Usage:
   relay-flow init [--force] [--task-plugin <name> --runner-plugin <name> --harness-plugin <name>]
                    [--executor-plugin <goworkflows|temporal>]
                    [--temporal-address <host:port>] [--temporal-namespace <name>]
+                   (interactive first run also authenticates and optionally registers repos)
   relay-flow task auth [task-plugin options]
   relay-flow serve [--recover] [--debug] [--background]
   relay-flow stop
@@ -168,6 +169,14 @@ Usage:
 // 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 {
+	if err := recoverFirstRunPublication(p); err != nil {
+		fmt.Fprintln(os.Stderr, "init: "+err.Error())
+		return exitFail
+	}
+	if err := cleanupFirstRunStaging(p); err != nil {
+		fmt.Fprintln(os.Stderr, "init: "+err.Error())
+		return exitFail
+	}
 	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)")
@@ -206,11 +215,17 @@ func cmdInit(p paths.Paths, args []string, stdin io.Reader) int {
 		fmt.Fprintln(os.Stderr, "init: database is missing; refusing to recreate existing durable state")
 		return exitFail
 	}
-	if err := os.MkdirAll(p.Root, 0o700); err != nil {
-		fmt.Fprintln(os.Stderr, err)
-		return exitFail
+	// A first interactive setup keeps the final home untouched until the
+	// selected task plugin has authenticated successfully. Scripted setup and
+	// --force retain the existing eager directory creation behavior.
+	firstRunInteractive := !*force && !configExists && !databaseExists && !flagged && interactiveInitTTY(stdin)
+	if !firstRunInteractive {
+		if err := os.MkdirAll(p.Root, 0o700); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		_ = os.Chmod(p.Root, 0o700)
 	}
-	_ = os.Chmod(p.Root, 0o700)
 	var unlock func()
 	if *force {
 		unlock, err = lockForForcedInit(p.Lock)
@@ -240,9 +255,9 @@ func cmdInit(p paths.Paths, args []string, stdin io.Reader) int {
 	switch {
 	case flagged:
 		names = []string{*taskName, *runnerName, *harnessName}
-	case isTTY(stdin):
+	case interactiveInitTTY(stdin):
 		var err error
-		names, err = pickPluginsInteractive()
+		names, err = interactiveInitPluginPick()
 		if err != nil {
 			fmt.Fprintln(os.Stderr, "init: "+err.Error())
 			return exitFail
@@ -258,7 +273,7 @@ func cmdInit(p paths.Paths, args []string, stdin io.Reader) int {
 			return exitFail
 		}
 	}
-	if executor == executorTemporal && isTTY(stdin) {
+	if executor == executorTemporal && interactiveInitTTY(stdin) {
 		address, namespace, err := promptTemporalSettings(*temporalAddress, *temporalNamespace)
 		if err != nil {
 			fmt.Fprintln(os.Stderr, "init: "+err.Error())
@@ -353,6 +368,19 @@ func cmdInit(p paths.Paths, args []string, stdin io.Reader) int {
 	} else {
 		cfg.HarnessConfig = config.Merge(harnessDefaults, cfg.HarnessConfig)
 	}
+	var stagedAuthDir string
+	if firstRunInteractive {
+		if names[0] == "beads" {
+			fmt.Println("Beads authentication is managed by the Beads workspace and Dolt setup; relay-flow does not store task credentials.")
+		}
+		var authErr error
+		cfg, stagedAuthDir, authErr = stageFirstRunAuthentication(p, cfg, names[0], stdin)
+		if authErr != nil {
+			fmt.Fprintln(os.Stderr, "init: task auth: "+authErr.Error())
+			return exitFail
+		}
+		defer os.RemoveAll(stagedAuthDir)
+	}
 	identity := projection.ExecutorIdentity{
 		ExecutorPlugin:    executor,
 		TemporalAddress:   cfg.TemporalAddress,
@@ -373,13 +401,30 @@ func cmdInit(p paths.Paths, args []string, stdin io.Reader) int {
 			return exitFail
 		}
 	}
-	if !databaseExists {
+	if !firstRunInteractive && !databaseExists {
 		if err := projection.InitDatabaseWithIdentity(p.Database, identity); err != nil {
 			fmt.Fprintln(os.Stderr, "init: "+err.Error())
 			return exitFail
 		}
 	}
-	if err := config.SaveMachine(p.Config, cfg); err != nil {
+	if firstRunInteractive {
+		if err := commitFirstRun(p, stagedAuthDir, identity); err != nil {
+			fmt.Fprintln(os.Stderr, "init: "+err.Error())
+			return exitFail
+		}
+		register, err := interactiveInitRepoPrompt()
+		if err != nil {
+			fmt.Fprintln(os.Stderr, "init: "+err.Error())
+			return exitFail
+		}
+		if register {
+			if err := interactiveInitRepoSetup(p, stdin); err != nil {
+				fmt.Fprintln(os.Stderr, "init: "+err.Error())
+				return exitFail
+			}
+			fmt.Println("Repository setup complete. The server is running; stop it with `relay-flow stop`.")
+		}
+	} else if err := config.SaveMachine(p.Config, cfg); err != nil {
 		fmt.Fprintln(os.Stderr, err)
 		return exitFail
 	}
@@ -540,55 +585,121 @@ func cmdServe(p paths.Paths, args []string) int {
 	return exitOK
 }
 
+var (
+	backgroundServeStartupTimeout = 10 * time.Second
+	backgroundServePollInterval   = 50 * time.Millisecond
+)
+
 func startBackgroundServe(p paths.Paths, recover, debug bool) error {
 	client := server.NewClient(p.Socket)
 	if serverResponding(client, 200*time.Millisecond) {
 		return fmt.Errorf("serve --background: server is already running")
 	}
-	executable, err := os.Executable()
+	deadline := time.Now().Add(backgroundServeStartupTimeout)
+	lockHeld, err := serverLockHeld(p.Lock)
 	if err != nil {
-		return fmt.Errorf("serve --background: resolve executable: %w", err)
+		return fmt.Errorf("serve --background: inspect server lock: %w", err)
 	}
-	childArgs := []string{"serve"}
-	if recover {
-		childArgs = append(childArgs, "--recover")
-	}
-	if debug {
-		childArgs = append(childArgs, "--debug")
+
+	var (
+		cmd           *exec.Cmd
+		wait          chan error
+		observedOwner = lockHeld
+		devNull       *os.File
+	)
+	if !lockHeld {
+		executable, resolveErr := os.Executable()
+		if resolveErr != nil {
+			return fmt.Errorf("serve --background: resolve executable: %w", resolveErr)
+		}
+		childArgs := []string{"serve"}
+		if recover {
+			childArgs = append(childArgs, "--recover")
+		}
+		if debug {
+			childArgs = append(childArgs, "--debug")
+		}
+		devNull, err = os.OpenFile(os.DevNull, os.O_RDWR, 0)
+		if err != nil {
+			return fmt.Errorf("serve --background: open %s: %w", os.DevNull, err)
+		}
+		defer devNull.Close()
+		cmd = exec.Command(executable, childArgs...)
+		cmd.Stdin, cmd.Stdout, cmd.Stderr = devNull, devNull, devNull
+		cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
+		if err := cmd.Start(); err != nil {
+			return fmt.Errorf("serve --background: start: %w; see %s", err, p.ServerLog)
+		}
+		wait = make(chan error, 1)
+		go func() { wait <- cmd.Wait() }()
 	}
-	devNull, err := os.OpenFile(os.DevNull, os.O_RDWR, 0)
-	if err != nil {
-		return fmt.Errorf("serve --background: open %s: %w", os.DevNull, err)
-	}
-	defer devNull.Close()
-	cmd := exec.Command(executable, childArgs...)
-	cmd.Stdin, cmd.Stdout, cmd.Stderr = devNull, devNull, devNull
-	cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
-	if err := cmd.Start(); err != nil {
-		return fmt.Errorf("serve --background: start: %w; see %s", err, p.ServerLog)
-	}
-	wait := make(chan error, 1)
-	go func() { wait <- cmd.Wait() }()
-	deadline := time.NewTimer(10 * time.Second)
-	defer deadline.Stop()
-	ticker := time.NewTicker(50 * time.Millisecond)
+
+	ticker := time.NewTicker(backgroundServePollInterval)
 	defer ticker.Stop()
 	for {
-		select {
-		case err := <-wait:
-			return fmt.Errorf("serve --background: server exited before readiness: %v; see %s", err, p.ServerLog)
-		case <-deadline.C:
-			_ = cmd.Process.Kill()
-			<-wait
+		if serverResponding(client, 200*time.Millisecond) {
+			return nil
+		}
+		if !time.Now().Before(deadline) {
+			if cmd != nil && wait != nil {
+				_ = cmd.Process.Kill()
+				<-wait
+			}
 			return fmt.Errorf("serve --background: startup timed out; see %s", p.ServerLog)
-		case <-ticker.C:
-			if serverResponding(client, 200*time.Millisecond) {
-				return nil
+		}
+		if observedOwner && wait == nil {
+			held, lockErr := serverLockHeld(p.Lock)
+			if lockErr != nil {
+				return fmt.Errorf("serve --background: inspect server lock: %w", lockErr)
+			}
+			if !held {
+				return fmt.Errorf("serve --background: server exited before readiness; see %s", p.ServerLog)
 			}
 		}
+		select {
+		case childErr := <-wait:
+			held, lockErr := serverLockHeld(p.Lock)
+			if lockErr != nil {
+				return fmt.Errorf("serve --background: inspect server lock: %w", lockErr)
+			}
+			if held {
+				// Another process acquired the lock while this child was
+				// starting. Wait for that owner instead of spawning again.
+				observedOwner = true
+				wait = nil
+				cmd = nil
+				continue
+			}
+			return fmt.Errorf("serve --background: server exited before readiness: %v; see %s", childErr, p.ServerLog)
+		case <-ticker.C:
+		}
 	}
 }
 
+func serverLockHeld(path string) (bool, error) {
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return false, nil
+		}
+		return false, err
+	}
+	defer f.Close()
+	if err := f.Chmod(0o600); err != nil {
+		return false, err
+	}
+	if err := syscall.Flock(int(f.Fd()), syscall.LOCK_EX|syscall.LOCK_NB); err != nil {
+		if err == syscall.EWOULDBLOCK || err == syscall.EAGAIN {
+			return true, nil
+		}
+		return false, err
+	}
+	if err := syscall.Flock(int(f.Fd()), syscall.LOCK_UN); err != nil {
+		return false, err
+	}
+	return false, nil
+}
+
 func serverResponding(client *server.Client, timeout time.Duration) bool {
 	ctx, cancel := context.WithTimeout(context.Background(), timeout)
 	defer cancel()
@@ -811,7 +922,7 @@ func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags,
 		}
 		registration, err := loadRepoRegistration(ctx, c, sets)
 		if err != nil {
-			fmt.Fprintln(os.Stderr, err)
+			fmt.Fprintln(os.Stderr, standaloneRepoServerHint(err))
 			return exitFail
 		}
 		taskCfg, err := registrationTaskConfig(registration, sets, flagName)
@@ -821,7 +932,7 @@ func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags,
 		}
 		info, err := c.RegisterRepo(ctx, repo.RegisterInput{Name: flagName, Path: flagPath, TaskConfig: taskCfg})
 		if err != nil {
-			fmt.Fprintln(os.Stderr, err)
+			fmt.Fprintln(os.Stderr, standaloneRepoServerHint(err))
 			return exitFail
 		}
 		fmt.Println(info.Name)
@@ -830,7 +941,7 @@ func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags,
 
 	registration, err := c.RepoRegistrationFields(ctx, nil)
 	if err != nil {
-		fmt.Fprintln(os.Stderr, err)
+		fmt.Fprintln(os.Stderr, standaloneRepoServerHint(err))
 		return exitFail
 	}
 
@@ -840,23 +951,17 @@ func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags,
 	}
 	candidates, err := c.DiscoverRepos(ctx)
 	if err != nil {
-		fmt.Fprintln(os.Stderr, err)
+		fmt.Fprintln(os.Stderr, standaloneRepoServerHint(err))
 		return exitFail
 	}
-	if len(candidates) == 0 {
-		fmt.Fprintln(os.Stderr, "repo register: runner discovered no repos")
+	registered, err := c.ListRepos(ctx)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, standaloneRepoServerHint(err))
 		return exitFail
 	}
-
-	selected := []int{}
-	options := make([]huh.Option[int], len(candidates))
-	for i, cand := range candidates {
-		options[i] = huh.NewOption(cand.Name+"  ("+cand.Path+")", i)
-	}
-	pickField := repoMultiSelect(options, &selected)
-	pick := huh.NewForm(huh.NewGroup(pickField))
-	if err := pick.Run(); err != nil {
-		fmt.Fprintln(os.Stderr, "repo register: "+err.Error())
+	candidates, selected, err := selectReposInteractive(ctx, c, candidates, registered)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "repo register: "+standaloneRepoServerHint(err).Error())
 		return exitFail
 	}
 
@@ -868,7 +973,7 @@ func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags,
 	if len(shared) > 0 {
 		dependent, err := c.RepoRegistrationFields(ctx, flatRegistrationValues(shared))
 		if err != nil {
-			fmt.Fprintln(os.Stderr, err)
+			fmt.Fprintln(os.Stderr, standaloneRepoServerHint(err))
 			return exitFail
 		}
 		registration = mergeRegistration(registration, dependent)
@@ -878,7 +983,7 @@ func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags,
 		}
 	}
 	if err := registerSelectedReposDynamic(ctx, c, candidates, selected, registration, shared); err != nil {
-		fmt.Fprintln(os.Stderr, "repo register: "+err.Error())
+		fmt.Fprintln(os.Stderr, "repo register: "+standaloneRepoServerHint(err).Error())
 		return exitFail
 	}
 	return exitOK
@@ -887,6 +992,8 @@ func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags,
 func repoMultiSelect(options []huh.Option[int], selected *[]int) *huh.MultiSelect[int] {
 	return huh.NewMultiSelect[int]().
 		Title("Select repositories").
+		Description("Press / to filter repositories; select [+] Add repository to add a runner resource.").
+		Filterable(true).
 		Options(options...).
 		Value(selected).
 		Validate(func(values []int) error {

package/cmd/relay-flow/onboarding.go

@@ -0,0 +1,344 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/charmbracelet/huh"
+	huhspinner "github.com/charmbracelet/huh/spinner"
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/execution/projection"
+	"github.com/rajpopat27/relay-flow/internal/paths"
+	"github.com/rajpopat27/relay-flow/internal/server"
+	"github.com/rajpopat27/relay-flow/internal/task"
+)
+
+// Small command-level seams keep the interactive orchestration testable
+// without changing task, runner, or server package boundaries.
+var (
+	interactiveInitTTY        = isTTY
+	interactiveInitPluginPick = pickPluginsInteractive
+	interactiveInitRepoPrompt = promptFirstRunRepositorySetup
+	interactiveInitRepoSetup  = runFirstRunRepositorySetup
+	firstRunRegistration      = cmdRepoRegister
+)
+
+// stageFirstRunAuthentication gives the selected task plugin its normal auth
+// entry point without exposing a partially initialized relay-flow home. Jira's
+// auth flow also writes the first mailbox-assignee default into config.yaml;
+// staging that file keeps the plugin's existing behavior while allowing the
+// final config, credentials, and database to be committed only after auth.
+func stageFirstRunAuthentication(p paths.Paths, cfg *config.Machine, plugin string, stdin io.Reader) (*config.Machine, string, error) {
+	if err := os.MkdirAll(filepath.Dir(p.Root), 0o700); err != nil {
+		return nil, "", fmt.Errorf("create initialization parent directory: %w", err)
+	}
+	stage, err := os.MkdirTemp(filepath.Dir(p.Root), ".relay-flow-init-")
+	if err != nil {
+		return nil, "", fmt.Errorf("create initialization staging directory: %w", err)
+	}
+	cleanup := func() {
+		_ = os.RemoveAll(stage)
+	}
+	if err := config.SaveMachine(filepath.Join(stage, "config.yaml"), cfg); err != nil {
+		cleanup()
+		return nil, "", fmt.Errorf("stage machine config: %w", err)
+	}
+
+	previousHome, hadHome := os.LookupEnv("RELAY_FLOW_HOME")
+	if err := os.Setenv("RELAY_FLOW_HOME", stage); err != nil {
+		cleanup()
+		return nil, "", fmt.Errorf("stage relay-flow home: %w", err)
+	}
+	authErr := task.Auth(context.Background(), plugin, nil, stdin)
+	if hadHome {
+		_ = os.Setenv("RELAY_FLOW_HOME", previousHome)
+	} else {
+		_ = os.Unsetenv("RELAY_FLOW_HOME")
+	}
+	if authErr != nil {
+		cleanup()
+		return nil, "", authErr
+	}
+
+	staged, err := config.LoadMachine(filepath.Join(stage, "config.yaml"))
+	if err != nil {
+		cleanup()
+		return nil, "", fmt.Errorf("load authenticated machine config: %w", err)
+	}
+	return staged, stage, nil
+}
+
+const firstRunPendingName = ".init-pending"
+
+type firstRunPending struct {
+	Credentials bool `json:"credentials"`
+}
+
+func firstRunPendingPath(p paths.Paths) string {
+	return filepath.Join(p.Root, firstRunPendingName)
+}
+
+// commitFirstRun publishes the staged config and task credentials only after
+// the durable database has been initialized. The pending marker makes the
+// multi-file publication recoverable if the process is interrupted; each
+// regular file is written with renameio through config.WriteAtomic.
+func commitFirstRun(p paths.Paths, stage string, identity projection.ExecutorIdentity) (err error) {
+	stagedConfig := filepath.Join(stage, "config.yaml")
+	stagedCredentials := filepath.Join(stage, "credentials.yaml")
+	configData, err := os.ReadFile(stagedConfig)
+	if err != nil {
+		return fmt.Errorf("read staged machine config: %w", err)
+	}
+	credentialsData, credentials, err := stagedCredentialsData(stagedCredentials)
+	if err != nil {
+		return err
+	}
+
+	for _, path := range []string{p.Config, p.Database, p.Credentials} {
+		if _, statErr := os.Stat(path); statErr == nil {
+			return fmt.Errorf("initialization artifact %s already exists; refusing to overwrite it", path)
+		} else if !os.IsNotExist(statErr) {
+			return fmt.Errorf("stat initialization artifact %s: %w", path, statErr)
+		}
+	}
+	if err := os.MkdirAll(p.Root, 0o700); err != nil {
+		return fmt.Errorf("create relay-flow home: %w", err)
+	}
+	if err := os.Chmod(p.Root, 0o700); err != nil {
+		return fmt.Errorf("chmod relay-flow home: %w", err)
+	}
+
+	pending := firstRunPending{Credentials: credentials}
+	pendingData, err := json.Marshal(pending)
+	if err != nil {
+		return fmt.Errorf("marshal initialization marker: %w", err)
+	}
+	if err := config.WriteAtomic(firstRunPendingPath(p), pendingData, 0o600); err != nil {
+		return fmt.Errorf("write initialization marker: %w", err)
+	}
+	published := false
+	defer func() {
+		if published {
+			return
+		}
+		_ = removeFirstRunArtifacts(p)
+	}()
+
+	if err := projection.InitDatabaseWithIdentity(p.Database, identity); err != nil {
+		return fmt.Errorf("initialize durable state: %w", err)
+	}
+	if err := config.WriteAtomic(p.Config, configData, 0o600); err != nil {
+		return fmt.Errorf("publish machine config: %w", err)
+	}
+	if credentials {
+		if err := config.WriteAtomic(p.Credentials, credentialsData, 0o600); err != nil {
+			return fmt.Errorf("publish task credentials: %w", err)
+		}
+	}
+
+	// Once all durable artifacts exist, leave them in place even if marker
+	// cleanup is interrupted. The next init removes the marker idempotently.
+	published = true
+	if err := os.Remove(firstRunPendingPath(p)); err != nil && !os.IsNotExist(err) {
+		return fmt.Errorf("finish initialization publication: %w", err)
+	}
+	if err := syncDirectory(p.Root); err != nil {
+		return fmt.Errorf("sync relay-flow home: %w", err)
+	}
+	return nil
+}
+
+func stagedCredentialsData(path string) ([]byte, bool, error) {
+	data, err := os.ReadFile(path)
+	if err == nil {
+		return data, true, nil
+	}
+	if os.IsNotExist(err) {
+		return nil, false, nil
+	}
+	return nil, false, fmt.Errorf("read staged task credentials: %w", err)
+}
+
+func removeFirstRunArtifacts(p paths.Paths) error {
+	// Keep the marker until every owned artifact is gone. If cleanup fails or
+	// the process is interrupted, the next init can retry from the marker.
+	for _, path := range []string{
+		p.Config, p.Credentials, p.Database,
+		p.Database + "-wal", p.Database + "-shm",
+	} {
+		if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
+			return fmt.Errorf("remove initialization artifact %s: %w", path, err)
+		}
+	}
+	if _, err := os.Stat(p.Root); os.IsNotExist(err) {
+		return nil
+	} else if err != nil {
+		return fmt.Errorf("stat relay-flow home: %w", err)
+	}
+	// Persist the artifact removals while the marker still protects recovery.
+	if err := syncDirectory(p.Root); err != nil {
+		return fmt.Errorf("sync cleaned initialization artifacts: %w", err)
+	}
+	if err := os.Remove(firstRunPendingPath(p)); err != nil && !os.IsNotExist(err) {
+		return fmt.Errorf("remove initialization marker: %w", err)
+	}
+	if err := syncDirectory(p.Root); err != nil {
+		return fmt.Errorf("sync initialization marker removal: %w", err)
+	}
+	return nil
+}
+
+func syncDirectory(path string) error {
+	dir, err := os.Open(path)
+	if err != nil {
+		return err
+	}
+	defer dir.Close()
+	return dir.Sync()
+}
+
+// recoverFirstRunPublication completes marker cleanup for a complete
+// publication or removes only the artifacts owned by an incomplete first-run.
+// It runs before init's normal existing-state refusal so an interrupted setup
+// can be retried instead of wedging the home.
+func recoverFirstRunPublication(p paths.Paths) error {
+	marker := firstRunPendingPath(p)
+	raw, err := os.ReadFile(marker)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		return fmt.Errorf("read initialization marker: %w", err)
+	}
+	var pending firstRunPending
+	if err := json.Unmarshal(raw, &pending); err != nil {
+		if cleanupErr := removeFirstRunArtifacts(p); cleanupErr != nil {
+			return fmt.Errorf("recover invalid initialization marker: %v; cleanup: %w", err, cleanupErr)
+		}
+		return nil
+	}
+	complete := true
+	for _, path := range []string{p.Config, p.Database} {
+		if _, statErr := os.Stat(path); statErr != nil {
+			if !os.IsNotExist(statErr) {
+				return fmt.Errorf("inspect initialization artifact %s: %w", path, statErr)
+			}
+			complete = false
+		}
+	}
+	if pending.Credentials {
+		if _, statErr := os.Stat(p.Credentials); statErr != nil {
+			if !os.IsNotExist(statErr) {
+				return fmt.Errorf("inspect initialization credentials: %w", statErr)
+			}
+			complete = false
+		}
+	}
+	if complete {
+		if err := os.Remove(marker); err != nil && !os.IsNotExist(err) {
+			return fmt.Errorf("remove completed initialization marker: %w", err)
+		}
+		return syncDirectory(p.Root)
+	}
+	return removeFirstRunArtifacts(p)
+}
+
+func cleanupFirstRunStaging(p paths.Paths) error {
+	entries, err := os.ReadDir(filepath.Dir(p.Root))
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		return fmt.Errorf("read initialization staging parent: %w", err)
+	}
+	for _, entry := range entries {
+		if !entry.IsDir() || !strings.HasPrefix(entry.Name(), ".relay-flow-init-") {
+			continue
+		}
+		if err := os.RemoveAll(filepath.Join(filepath.Dir(p.Root), entry.Name())); err != nil {
+			return fmt.Errorf("remove stale initialization staging %s: %w", entry.Name(), err)
+		}
+	}
+	return nil
+}
+
+func promptFirstRunRepositorySetup() (bool, error) {
+	register := false
+	form := huh.NewForm(huh.NewGroup(
+		huh.NewConfirm().
+			Title("Register repositories now?").
+			Description("You can register repositories later with relay-flow repo register.").
+			Affirmative("Yes").
+			Negative("No").
+			Value(&register),
+	))
+	if err := form.Run(); err != nil {
+		return false, fmt.Errorf("repository setup prompt: %w", err)
+	}
+	return register, nil
+}
+
+// runFirstRunRepositorySetup starts or reuses the server, showing a small
+// terminal spinner while the Unix socket becomes ready, then delegates to the
+// existing interactive repository-registration flow.
+func runFirstRunRepositorySetup(p paths.Paths, stdin io.Reader) error {
+	if err := runOnboardingSpinner("Starting relay-flow server", func() error {
+		return ensureFirstRunServer(p)
+	}); err != nil {
+		return err
+	}
+
+	if code := firstRunRegistration(server.NewClient(p.Socket), "", "", nil, stdin); code != exitOK {
+		return fmt.Errorf("repository registration failed")
+	}
+	return nil
+}
+
+func ensureFirstRunServer(p paths.Paths) error {
+	client := server.NewClient(p.Socket)
+	if serverResponding(client, 200*time.Millisecond) {
+		return nil
+	}
+	if err := startBackgroundServe(p, false, false); err != nil {
+		// A server may have become ready between the initial probe and the
+		// child launch. Reuse it when that race is harmless.
+		if serverResponding(client, 200*time.Millisecond) {
+			return nil
+		}
+		return err
+	}
+	return nil
+}
+
+// runOnboardingSpinner keeps the server-readiness wait visible without
+// changing the existing Huh forms or the non-interactive command paths.
+func runOnboardingSpinner(title string, action func() error) error {
+	return huhspinner.New().
+		Type(huhspinner.Line).
+		Title(title + "...").
+		Output(os.Stderr).
+		ActionWithErr(func(context.Context) error { return action() }).
+		Run()
+}
+
+// standaloneRepoServerHint adds the actionable startup hint required for the
+// independent repo-register command while preserving server/API messages for
+// failures that occur after a successful connection.
+func standaloneRepoServerHint(err error) error {
+	if err == nil {
+		return nil
+	}
+	message := err.Error()
+	for _, marker := range []string{"dial unix", "connect: no such file or directory", "connection refused"} {
+		if strings.Contains(message, marker) {
+			return fmt.Errorf("%w; start the server with `relay-flow serve --background` (or use the guided init path)", err)
+		}
+	}
+	return err
+}