relay-flow 0.2.7-alpha → 0.2.9-alpha

package/internal/runner/orca/orca.go

@@ -13,6 +13,7 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
+	"path/filepath"
 	"strings"
 
 	"github.com/rajpopat27/relay-flow/internal/config"
@@ -65,6 +66,42 @@ func (a *adapter) DiscoverRepos(ctx context.Context) ([]runner.RepoCandidate, er
 	return out, nil
 }
 
+// EnsureRepo makes an Orca repository available by canonical path. Orca
+// derives its display name from the path, so the relay-flow registration name
+// is intentionally not used as the Orca identity.
+func (a *adapter) EnsureRepo(ctx context.Context, name, path string) error {
+	slog.Debug("orca call", "op", "ensure-repo", "repo", name)
+	canonical := normalizePath(path)
+	if canonical == "" {
+		err := fmt.Errorf("orca: repository %q has an empty path", name)
+		slog.Info("orca outcome", "op", "ensure-repo", "repo", name, "result", "error", "error", sanitizeErr(err))
+		return err
+	}
+	repos, err := a.cli.ListRepos(ctx)
+	if err != nil {
+		slog.Info("orca outcome", "op", "ensure-repo", "repo", name, "result", "error", "error", sanitizeErr(err))
+		return err
+	}
+	for _, r := range repos {
+		if normalizePath(r.Path) == canonical {
+			slog.Info("orca outcome", "op", "ensure-repo", "repo", name, "result", "exists")
+			return nil
+		}
+	}
+	adder, ok := a.cli.(orcacli.RepoRegistrar)
+	if !ok {
+		err := fmt.Errorf("orca: repository provisioning is unavailable")
+		slog.Info("orca outcome", "op", "ensure-repo", "repo", name, "result", "error", "error", sanitizeErr(err))
+		return err
+	}
+	if err := adder.AddRepo(ctx, canonical); err != nil {
+		slog.Info("orca outcome", "op", "ensure-repo", "repo", name, "result", "error", "error", sanitizeErr(err))
+		return err
+	}
+	slog.Info("orca outcome", "op", "ensure-repo", "repo", name, "result", "created")
+	return nil
+}
+
 // ValidateRepo verifies the named repo exists in Orca at the given path.
 func (a *adapter) ValidateRepo(ctx context.Context, name, path string) error {
 	if _, err := a.repoID(ctx, name, path); err != nil {
@@ -73,22 +110,41 @@ func (a *adapter) ValidateRepo(ctx context.Context, name, path string) error {
 	return nil
 }
 
-// repoID resolves a registered repo to its Orca repo ID. The repo path is
-// the stable identity (the Orca repo ID is an internal detail that can
-// change across machines); name is matched as a secondary check.
+// repoID resolves a registered repo to its Orca repo ID. The canonical repo
+// path is the stable identity (the Orca repo ID is an internal detail that
+// can change across machines); relay-flow's name is independent metadata.
 func (a *adapter) repoID(ctx context.Context, name, path string) (string, error) {
+	canonical := normalizePath(path)
+	if canonical == "" {
+		return "", fmt.Errorf("orca: repo %q has an empty path", name)
+	}
 	repos, err := a.cli.ListRepos(ctx)
 	if err != nil {
 		return "", err
 	}
 	for _, r := range repos {
-		if r.Path == path && r.DisplayName == name {
+		if normalizePath(r.Path) == canonical {
 			return r.ID, nil
 		}
 	}
 	return "", fmt.Errorf("orca: repo %q at %q not registered", name, path)
 }
 
+func normalizePath(path string) string {
+	if strings.TrimSpace(path) == "" {
+		return ""
+	}
+	absolute, err := filepath.Abs(path)
+	if err != nil {
+		return filepath.Clean(path)
+	}
+	absolute = filepath.Clean(absolute)
+	if resolved, err := filepath.EvalSymlinks(absolute); err == nil {
+		return filepath.Clean(resolved)
+	}
+	return absolute
+}
+
 // --- Environment ---
 
 // EnsureEnvironment returns the ticket-scoped worktree, creating it from the
@@ -198,6 +254,10 @@ func primaryBranch(w *orcacli.Worktree) string {
 func (a *adapter) CloseTerminal(ctx context.Context, terminal runner.Terminal) error {
 	slog.Debug("orca call", "op", "close-terminal", "title", terminal.Title, "handle", terminal.ID)
 	err := a.cli.CloseTerminal(ctx, terminal.ID)
+	if errors.Is(err, orcacli.ErrTerminalUnavailable) {
+		slog.Info("orca outcome", "op", "close-terminal", "title", terminal.Title, "result", "absent")
+		return nil
+	}
 	if err != nil {
 		slog.Info("orca outcome", "op", "close-terminal", "title", terminal.Title, "result", "error", "error", sanitizeErr(err))
 	} else {
@@ -386,14 +446,10 @@ func (a *adapter) CloseTerminals(ctx context.Context, spec runner.RunSpec) error
 		if !strings.HasPrefix(t.Title, prefix) {
 			continue
 		}
-		// 9.5: one outcome line per actual terminal close, with its title.
-		slog.Debug("orca call", "op", "close-terminal", "title", t.Title, "handle", t.Handle)
-		if err := a.cli.CloseTerminal(ctx, t.Handle); err != nil {
-			slog.Info("orca outcome", "op", "close-terminal", "title", t.Title, "result", "error", "error", sanitizeErr(err))
+		if err := a.CloseTerminal(ctx, runner.Terminal{ID: t.Handle, Title: t.Title}); err != nil {
 			slog.Info("orca outcome", "op", "close-terminals", "ticket", spec.TicketKey, "result", "error", "error", sanitizeErr(err))
 			return fmt.Errorf("close terminal %q: %w", t.Title, err)
 		}
-		slog.Info("orca outcome", "op", "close-terminal", "title", t.Title, "result", "ok")
 		closed++
 	}
 	slog.Info("orca outcome", "op", "close-terminals", "ticket", spec.TicketKey, "result", "ok", "closed", closed)
@@ -443,3 +499,6 @@ func (a *adapter) findEnvironment(ctx context.Context, spec runner.RunSpec) (run
 	}
 	return runner.Environment{}, false, nil
 }
+
+var _ runner.Runner = (*adapter)(nil)
+var _ runner.RepoRegistrar = (*adapter)(nil)

package/internal/runner/orca/orca_test.go

@@ -50,6 +50,9 @@ type fakeCLI struct {
 	showHandles       []string
 	createCommands    []string
 	createN           int
+	closedHandles     []string
+	closeErrors       map[string]error
+	deletedWorktrees  []string
 }
 
 func (f *fakeCLI) ListRepos(context.Context) ([]orcacli.Repo, error) { return f.repos, nil }
@@ -72,7 +75,10 @@ func (f *fakeCLI) SetWorktreeStatus(_ context.Context, _, status string) error {
 	f.status = status
 	return nil
 }
-func (f *fakeCLI) DeleteWorktree(context.Context, string) error { return nil }
+func (f *fakeCLI) DeleteWorktree(_ context.Context, worktreeID string) error {
+	f.deletedWorktrees = append(f.deletedWorktrees, worktreeID)
+	return nil
+}
 func (f *fakeCLI) ShowTerminal(_ context.Context, handle string) (orcacli.Terminal, error) {
 	f.showHandles = append(f.showHandles, handle)
 	t, ok := f.terminals[handle]
@@ -95,7 +101,59 @@ func (f *fakeCLI) CreateTerminal(_ context.Context, _ string, title, command str
 	f.terminals[handle] = orcacli.Terminal{Handle: handle, Title: title, Connected: true}
 	return handle, nil
 }
-func (f *fakeCLI) CloseTerminal(context.Context, string) error { return nil }
+func (f *fakeCLI) CloseTerminal(_ context.Context, handle string) error {
+	f.closedHandles = append(f.closedHandles, handle)
+	if err, ok := f.closeErrors[handle]; ok {
+		return err
+	}
+	return nil
+}
+
+type repoAddingCLI struct {
+	*fakeCLI
+	addPaths []string
+	addErr   error
+}
+
+func (f *repoAddingCLI) AddRepo(_ context.Context, path string) error {
+	f.addPaths = append(f.addPaths, path)
+	return f.addErr
+}
+
+func TestEnsureRepoSkipsAnExistingCanonicalPath(t *testing.T) {
+	path := t.TempDir()
+	fx := &repoAddingCLI{fakeCLI: &fakeCLI{repos: []orcacli.Repo{{ID: "r1", DisplayName: "runner-name", Path: path}}}}
+	a, err := New(fx, config.RawValues{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := a.(runner.RepoRegistrar).EnsureRepo(context.Background(), "relay-name", path+"/."); err != nil {
+		t.Fatal(err)
+	}
+	if len(fx.addPaths) != 0 {
+		t.Fatalf("AddRepo calls = %v, want none for an existing path", fx.addPaths)
+	}
+}
+
+func TestEnsureRepoAddsMissingPathAndPropagatesFailures(t *testing.T) {
+	path := t.TempDir()
+	fx := &repoAddingCLI{fakeCLI: &fakeCLI{}}
+	a, err := New(fx, config.RawValues{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := a.(runner.RepoRegistrar).EnsureRepo(context.Background(), "payments", path); err != nil {
+		t.Fatal(err)
+	}
+	if len(fx.addPaths) != 1 || fx.addPaths[0] != path {
+		t.Fatalf("AddRepo calls = %v, want [%q]", fx.addPaths, path)
+	}
+
+	fx.addErr = errors.New("orca unavailable")
+	if err := a.(runner.RepoRegistrar).EnsureRepo(context.Background(), "other", t.TempDir()); err == nil || !strings.Contains(err.Error(), "orca unavailable") {
+		t.Fatalf("EnsureRepo error = %v, want AddRepo failure", err)
+	}
+}
 
 // 9.16: when the repo's primary worktree is on master (refs/heads/master),
 // EnsureEnvironment must pass --base-branch master (via CreateWorktree), not
@@ -290,6 +348,80 @@ func TestCreateTerminalAlwaysCreatesAndTreatsCommandAsOpaque(t *testing.T) {
 	}
 }
 
+func TestCloseTerminalTreatsUnavailableAsAbsent(t *testing.T) {
+	fx := &fakeCLI{closeErrors: map[string]error{
+		"term-stale": orcacli.ErrTerminalUnavailable,
+	}}
+	a, err := New(fx, config.RawValues{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := a.CloseTerminal(context.Background(), runner.Terminal{ID: "term-stale", Title: "PAY-1:implement"}); err != nil {
+		t.Fatalf("CloseTerminal(stale) = %v, want nil", err)
+	}
+	if len(fx.closedHandles) != 1 || fx.closedHandles[0] != "term-stale" {
+		t.Fatalf("closed handles = %v, want [term-stale]", fx.closedHandles)
+	}
+}
+
+func TestCloseTerminalPropagatesGenuineFailure(t *testing.T) {
+	wantErr := errors.New("orca permission denied")
+	fx := &fakeCLI{closeErrors: map[string]error{"term-failed": wantErr}}
+	a, err := New(fx, config.RawValues{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := a.CloseTerminal(context.Background(), runner.Terminal{ID: "term-failed", Title: "PAY-1:implement"}); !errors.Is(err, wantErr) {
+		t.Fatalf("CloseTerminal(genuine failure) = %v, want %v", err, wantErr)
+	}
+}
+
+func TestCloseTerminalsContinuesAfterStaleHandle(t *testing.T) {
+	fx := &fakeCLI{
+		repos:     []orcacli.Repo{{ID: "r1", DisplayName: "app", Path: "/srv/app"}},
+		worktrees: []orcacli.Worktree{{ID: "wt-PAY-1", RepoID: "r1", DisplayName: "PAY-1"}},
+		listedTerminals: []orcacli.Terminal{
+			{Handle: "term-stale", Title: "PAY-1:stale", Connected: true},
+			{Handle: "term-live", Title: "PAY-1:implement", Connected: true},
+			{Handle: "term-user", Title: "shell", Connected: true},
+		},
+		closeErrors: map[string]error{"term-stale": orcacli.ErrTerminalUnavailable},
+	}
+	a, err := New(fx, config.RawValues{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := a.CloseTerminals(context.Background(), runner.RunSpec{
+		RepoName: "app", RepoPath: "/srv/app", TicketKey: "PAY-1",
+	}); err != nil {
+		t.Fatalf("CloseTerminals = %v, want nil after stale handle", err)
+	}
+	if len(fx.closedHandles) != 2 || fx.closedHandles[0] != "term-stale" || fx.closedHandles[1] != "term-live" {
+		t.Fatalf("closed handles = %v, want stale and live run terminals", fx.closedHandles)
+	}
+}
+
+func TestCleanupRunDeletesWorktreeAfterStaleHandle(t *testing.T) {
+	fx := &fakeCLI{
+		repos:           []orcacli.Repo{{ID: "r1", DisplayName: "app", Path: "/srv/app"}},
+		worktrees:       []orcacli.Worktree{{ID: "wt-PAY-1", RepoID: "r1", DisplayName: "PAY-1"}},
+		listedTerminals: []orcacli.Terminal{{Handle: "term-stale", Title: "PAY-1:implement", Connected: true}},
+		closeErrors:     map[string]error{"term-stale": orcacli.ErrTerminalUnavailable},
+	}
+	a, err := New(fx, config.RawValues{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := a.CleanupRun(context.Background(), runner.RunSpec{
+		RepoName: "app", RepoPath: "/srv/app", TicketKey: "PAY-1",
+	}); err != nil {
+		t.Fatalf("CleanupRun = %v, want nil after stale handle", err)
+	}
+	if len(fx.deletedWorktrees) != 1 || fx.deletedWorktrees[0] != "wt-PAY-1" {
+		t.Fatalf("deleted worktrees = %v, want [wt-PAY-1]", fx.deletedWorktrees)
+	}
+}
+
 // An existing ticket branch must win even over a configured baseRef. Passing
 // any other base would make Orca hit its branch-name collision behavior.
 func TestEnsureEnvironment_ExistingTicketBranchAvoidsCollision(t *testing.T) {

package/internal/runner/orca/orcacli/orcacli.go

@@ -57,8 +57,22 @@ type Client interface {
 // CLI is the production Client backed by the orca binary.
 type CLI struct{}
 
+// RepoRegistrar is the optional repository-provisioning seam used by the
+// runner adapter. Keeping it separate from Client lets existing read-only
+// test clients remain focused on the runtime operations they exercise.
+type RepoRegistrar interface {
+	AddRepo(ctx context.Context, path string) error
+}
+
 func New() *CLI { return &CLI{} }
 
+// AddRepo registers an existing local repository with Orca. Orca derives its
+// display name from the path; relay-flow keeps the user-facing registration
+// name separately.
+func (CLI) AddRepo(ctx context.Context, path string) error {
+	return run(ctx, "repo", "add", "--path", path, "--json")
+}
+
 func (CLI) ListRepos(ctx context.Context) ([]Repo, error) {
 	var res struct {
 		Result struct {
@@ -194,7 +208,13 @@ func (CLI) CreateTerminal(ctx context.Context, ticketKey, title, command string)
 }
 
 func (CLI) CloseTerminal(ctx context.Context, handle string) error {
-	return run(ctx, "terminal", "close", "--terminal", handle, "--json")
+	if err := run(ctx, "terminal", "close", "--terminal", handle, "--json"); err != nil {
+		if strings.Contains(err.Error(), "terminal_handle_stale") {
+			return ErrTerminalUnavailable
+		}
+		return err
+	}
+	return nil
 }
 
 func run(ctx context.Context, args ...string) error {

package/internal/runner/orca/orcacli/orcacli_test.go

@@ -2,6 +2,7 @@ package orcacli
 
 import (
 	"context"
+	"errors"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -30,6 +31,9 @@ func TestCLIContractsAgainstCapturedRealOutput(t *testing.T) {
 		t.Fatalf("ListWorktrees = %+v", worktrees)
 	}
 
+	if err := cli.AddRepo(ctx, "/work/new"); err != nil {
+		t.Fatal(err)
+	}
 	if err := cli.CreateWorktree(ctx, "PAY-101", "repo-1", "wt-main", "origin/alice/PAY-101"); err != nil {
 		t.Fatal(err)
 	}
@@ -80,6 +84,24 @@ func TestStrictFakeOrcaRejectsMissingFlags(t *testing.T) {
 	}
 }
 
+func TestCloseTerminalMapsStaleHandleToUnavailable(t *testing.T) {
+	installStrictFakeOrca(t)
+	cli := New()
+
+	err := cli.CloseTerminal(context.Background(), "term-stale")
+	if !errors.Is(err, ErrTerminalUnavailable) {
+		t.Fatalf("CloseTerminal(stale) = %v, want ErrTerminalUnavailable", err)
+	}
+
+	err = cli.CloseTerminal(context.Background(), "term-unknown")
+	if err == nil {
+		t.Fatal("CloseTerminal(unknown) = nil, want the CLI failure")
+	}
+	if errors.Is(err, ErrTerminalUnavailable) {
+		t.Fatalf("CloseTerminal(unknown) = %v, incorrectly classified as stale", err)
+	}
+}
+
 func TestFindExistingBranchLocalOnly(t *testing.T) {
 	repo := newGitRepo(t)
 	runGit(t, repo, "branch", "alice/PAY-101")

package/internal/runner/orca/orcacli/testdata/strict-orca.sh

@@ -4,6 +4,8 @@ set -eu
 fixture=
 if [ "$#" -eq 3 ] && [ "$1" = repo ] && [ "$2" = list ] && [ "$3" = --json ]; then
   fixture=repo-list.json
+elif [ "$#" -eq 5 ] && [ "$1" = repo ] && [ "$2" = add ] && [ "$3" = --path ] && [ "$4" = /work/new ] && [ "$5" = --json ]; then
+  fixture=repo-list.json
 elif [ "$#" -eq 3 ] && [ "$1" = worktree ] && [ "$2" = list ] && [ "$3" = --json ]; then
   fixture=worktree-list.json
 elif [ "$#" -eq 11 ] && [ "$1" = worktree ] && [ "$2" = create ] && [ "$3" = --name ] && [ "$4" = PAY-101 ] && [ "$5" = --repo ] && [ "$6" = id:repo-1 ] && [ "$7" = --parent-worktree ] && [ "$8" = worktree:wt-main ] && [ "$9" = --base-branch ] && [ "${10}" = origin/alice/PAY-101 ] && [ "${11}" = --json ]; then
@@ -20,6 +22,9 @@ elif [ "$#" -eq 8 ] && [ "$1" = terminal ] && [ "$2" = send ] && [ "$3" = --term
   fixture=terminal-send.json
 elif [ "$#" -eq 9 ] && [ "$1" = terminal ] && [ "$2" = create ] && [ "$3" = --worktree ] && [ "$4" = name:PAY-101 ] && [ "$5" = --title ] && [ "$6" = PAY-101:implement ] && [ "$7" = --command ] && [ "$8" = 'echo hello' ] && [ "$9" = --json ]; then
   fixture=terminal-create.json
+elif [ "$#" -eq 5 ] && [ "$1" = terminal ] && [ "$2" = close ] && [ "$3" = --terminal ] && [ "$4" = term-stale ] && [ "$5" = --json ]; then
+  printf '%s\n' '{"ok":false,"error":{"code":"terminal_handle_stale","message":"terminal_handle_stale"}}'
+  exit 1
 elif [ "$#" -eq 5 ] && [ "$1" = terminal ] && [ "$2" = close ] && [ "$3" = --terminal ] && [ "$4" = term-1 ] && [ "$5" = --json ]; then
   fixture=terminal-close.json
 else

package/internal/runner/runner.go

@@ -24,6 +24,15 @@ type RepoCandidate struct {
 	Path string `json:"path"`
 }
 
+// RepoRegistrar is the optional runner capability used by repository
+// registration. Runners that manage an external repository/workspace can
+// make the resource available before relay-flow persists the repo entry.
+// Runners without a provisioning primitive still use ValidateRepo through
+// the repo service.
+type RepoRegistrar interface {
+	EnsureRepo(context.Context, string, string) error
+}
+
 type Environment struct {
 	ID   string `json:"id"`
 	Path string `json:"path"`

package/internal/server/api_test.go

@@ -2,15 +2,20 @@ package server_test
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
 	"fmt"
 	"io"
 	"net/http"
+	"path/filepath"
 	"strings"
 	"testing"
 	"time"
 
+	"github.com/rajpopat27/relay-flow/internal/config"
 	"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"
 )
@@ -287,6 +292,66 @@ func TestRunEndpointsExposeRetryDetails(t *testing.T) {
 	}
 }
 
+func TestRepoTaskFieldsSupportsInitialGetAndDependentPost(t *testing.T) {
+	fake := &fakeServices{}
+	c, cleanup := startHandler(t, fake)
+	defer cleanup()
+
+	code, env := do(t, c, http.MethodGet, "http://relay/repos/task-fields", nil)
+	if code != http.StatusOK || !env.OK || !bytes.Contains(env.Data, []byte(`"fields"`)) {
+		t.Fatalf("GET /repos/task-fields: code=%d env=%+v", code, env)
+	}
+	code, env = do(t, c, http.MethodPost, "http://relay/repos/task-fields", []byte(`{"values":{"project":"PAY"}}`))
+	if code != http.StatusOK || !env.OK || len(fake.registrationValues) != 2 {
+		t.Fatalf("POST /repos/task-fields: code=%d env=%+v values=%v", code, env, fake.registrationValues)
+	}
+	if fake.registrationValues[1]["project"] != "PAY" {
+		t.Fatalf("dependent registration values = %#v", fake.registrationValues[1])
+	}
+}
+
+func TestClientRepoRegistrationFieldsUsesGetThenPost(t *testing.T) {
+	fake := &fakeServices{}
+	dir := t.TempDir()
+	_, cleanup := startHandlerOnSocket(t, dir, fake)
+	defer cleanup()
+	client := server.NewClient(filepath.Join(dir, "server.sock"))
+	keys, err := client.RepoTaskFields(context.Background())
+	if err != nil || len(keys) != 2 || keys[0] != "project" || keys[1] != "component" {
+		t.Fatalf("documented task fields = %v, err=%v", keys, err)
+	}
+
+	initial, err := client.RepoRegistrationFields(context.Background(), nil)
+	if err != nil || len(initial.Fields) != 2 {
+		t.Fatalf("initial registration fields = %#v, err=%v", initial, err)
+	}
+	dependent, err := client.RepoRegistrationFields(context.Background(), config.RawValues{"project": "PAY"})
+	if err != nil || len(dependent.Fields) != 2 {
+		t.Fatalf("dependent registration fields = %#v, err=%v", dependent, err)
+	}
+	if len(fake.registrationValues) != 3 || fake.registrationValues[0] != nil || fake.registrationValues[1] != nil || fake.registrationValues[2]["project"] != "PAY" {
+		t.Fatalf("registration request values = %#v", fake.registrationValues)
+	}
+}
+
+func TestRepoEnsureEndpoint(t *testing.T) {
+	fake := &fakeServices{}
+	c, cleanup := startHandler(t, fake)
+	defer cleanup()
+	code, env := do(t, c, http.MethodPost, "http://relay/repos/ensure", []byte(`{"name":"payments","path":"/srv/payments"}`))
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("POST /repos/ensure: code=%d env=%+v, want 200 ok", code, env)
+	}
+	if len(fake.ensureRepoCalls) != 1 || fake.ensureRepoCalls[0] != (runner.RepoCandidate{Name: "payments", Path: "/srv/payments"}) {
+		t.Fatalf("EnsureRepo calls = %+v", fake.ensureRepoCalls)
+	}
+
+	code, env = do(t, c, http.MethodPost, "http://relay/repos/ensure", []byte(`{"name":"payments"}`))
+	if code != http.StatusBadRequest || env.OK {
+		t.Fatalf("invalid POST /repos/ensure: code=%d env=%+v, want 400", code, env)
+	}
+}
+
 func TestRepoOperations(t *testing.T) {
 	c, cleanup := startHandler(t, &fakeServices{})
 	defer cleanup()

package/internal/server/client.go

@@ -10,9 +10,11 @@ import (
 	"net/http"
 	"net/url"
 
+	"github.com/rajpopat27/relay-flow/internal/config"
 	"github.com/rajpopat27/relay-flow/internal/repo"
 	"github.com/rajpopat27/relay-flow/internal/run"
 	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/task"
 	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
@@ -134,8 +136,17 @@ func (c *Client) DiscoverRepos(ctx context.Context) ([]runner.RepoCandidate, err
 	return out, nil
 }
 
-// RepoTaskFields returns the task factory's required repo keys, matching
-// GET /repos/task-fields (server wraps the list as {"fields": [...]}).
+// EnsureRepo asks the configured runner to make a repository resource
+// available without persisting a relay-flow repo entry.
+func (c *Client) EnsureRepo(ctx context.Context, candidate runner.RepoCandidate) error {
+	payload, err := json.Marshal(candidate)
+	if err != nil {
+		return err
+	}
+	return c.call(ctx, http.MethodPost, "/repos/ensure", payload, nil)
+}
+
+// RepoTaskFields returns the documented initial required-key metadata.
 func (c *Client) RepoTaskFields(ctx context.Context) ([]string, error) {
 	var out struct {
 		Fields []string `json:"fields"`
@@ -146,6 +157,33 @@ func (c *Client) RepoTaskFields(ctx context.Context) ([]string, error) {
 	return out.Fields, nil
 }
 
+// RepoRegistrationFields returns task-plugin-owned repository prompts. Values
+// are flat registration inputs so plugins can discover dependent choices (for
+// example project statuses after project is selected). Initial discovery uses
+// the documented GET endpoint; dependent discovery uses POST.
+func (c *Client) RepoRegistrationFields(ctx context.Context, values config.RawValues) (task.Registration, error) {
+	if len(values) == 0 {
+		var out struct {
+			Registration task.Registration `json:"registration"`
+		}
+		if err := c.call(ctx, http.MethodGet, "/repos/task-fields", nil, &out); err != nil {
+			return task.Registration{}, err
+		}
+		return out.Registration, nil
+	}
+	payload, err := json.Marshal(struct {
+		Values config.RawValues `json:"values,omitempty"`
+	}{Values: values})
+	if err != nil {
+		return task.Registration{}, err
+	}
+	var out task.Registration
+	if err := c.call(ctx, http.MethodPost, "/repos/task-fields", payload, &out); err != nil {
+		return task.Registration{}, err
+	}
+	return out, nil
+}
+
 // RegisterRepo registers a repo by name/path with optional task config.
 func (c *Client) RegisterRepo(ctx context.Context, input repo.RegisterInput) (repo.Info, error) {
 	payload, _ := json.Marshal(input)

package/internal/server/fixture_test.go

@@ -12,10 +12,12 @@ import (
 	"path/filepath"
 	"testing"
 
+	"github.com/rajpopat27/relay-flow/internal/config"
 	"github.com/rajpopat27/relay-flow/internal/repo"
 	"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"
 )
 
@@ -23,20 +25,23 @@ import (
 // seams. activeWorkflows seeds workflows with an active run (drives 409);
 // failRepos forces a 500; slowReport simulates a long-running report call.
 type fakeServices struct {
-	activeWorkflows  map[string]bool
-	failRepos        bool
-	slowReport       chan struct{}
-	workflows        map[string]*workflow.Workflow
-	repos            map[string]repo.Info
-	runs             []run.Run
-	shutdownCh       chan struct{}
-	registrations    []run.NodeRuntimeRegistration
-	runtimeAck       run.NodeRuntimeRegistrationAck
-	processedReports map[string]bool
-	submittedReports int
-	restartRun       run.Run
-	restartErr       error
-	restarts         []string
+	activeWorkflows    map[string]bool
+	failRepos          bool
+	slowReport         chan struct{}
+	workflows          map[string]*workflow.Workflow
+	repos              map[string]repo.Info
+	runs               []run.Run
+	shutdownCh         chan struct{}
+	registrations      []run.NodeRuntimeRegistration
+	runtimeAck         run.NodeRuntimeRegistrationAck
+	processedReports   map[string]bool
+	submittedReports   int
+	restartRun         run.Run
+	restartErr         error
+	restarts           []string
+	registrationValues []config.RawValues
+	ensureRepoCalls    []runner.RepoCandidate
+	ensureRepoErr      error
 }
 
 func (f *fakeServices) SubmitWorkflow(_ context.Context, yaml []byte) (*workflow.Workflow, error) {
@@ -152,8 +157,14 @@ func (f *fakeServices) DiscoverRepos(context.Context) ([]runner.RepoCandidate, e
 	return []runner.RepoCandidate{{Name: "payments", Path: "/srv/payments"}}, nil
 }
 
-func (f *fakeServices) TaskFields(context.Context) ([]string, error) {
-	return []string{"status", "labels"}, nil
+func (f *fakeServices) EnsureRepo(_ context.Context, candidate runner.RepoCandidate) error {
+	f.ensureRepoCalls = append(f.ensureRepoCalls, candidate)
+	return f.ensureRepoErr
+}
+
+func (f *fakeServices) TaskRegistrationFields(_ context.Context, values config.RawValues) ([]task.RegistrationField, error) {
+	f.registrationValues = append(f.registrationValues, values)
+	return []task.RegistrationField{{Key: "project", Title: "Project"}, {Key: "component", Title: "Component", Derived: true}}, nil
 }
 
 func (f *fakeServices) RegisterRepo(_ context.Context, input repo.RegisterInput) (repo.Info, error) {