relay-flow 0.2.8-alpha → 0.2.10-alpha

package/internal/runner/herdr/herdrcli/operations.go

@@ -26,6 +26,7 @@ type worktreeSourceResponse struct {
 	RepoName           string `json:"repo_name"`
 	RepoRoot           string `json:"repo_root"`
 	SourceCheckoutPath string `json:"source_checkout_path"`
+	SourceWorkspaceID  string `json:"source_workspace_id"`
 }
 
 type tabResponse struct {
@@ -72,6 +73,20 @@ func (c *CLI) Snapshot(ctx context.Context) (Snapshot, error) {
 	}, nil
 }
 
+// CreateWorkspace opens a repository path as a Herdr workspace. A source
+// workspace is enough for repository discovery; ticket worktrees are still
+// created lazily by EnsureEnvironment.
+func (c *CLI) CreateWorkspace(ctx context.Context, cwd, label string) (Workspace, error) {
+	var response struct {
+		Workspace workspaceResponse `json:"workspace"`
+	}
+	if err := c.runJSON(ctx, "workspace create", &response,
+		"workspace", "create", "--cwd", cwd, "--label", label, "--no-focus"); err != nil {
+		return Workspace{}, err
+	}
+	return convertWorkspace(response.Workspace), nil
+}
+
 func (c *CLI) WorktreeList(ctx context.Context, repoPath string) (WorktreeListing, error) {
 	var response struct {
 		Source    worktreeSourceResponse `json:"source"`
@@ -85,6 +100,7 @@ func (c *CLI) WorktreeList(ctx context.Context, repoPath string) (WorktreeListin
 			RepoName:           response.Source.RepoName,
 			RepoRoot:           response.Source.RepoRoot,
 			SourceCheckoutPath: response.Source.SourceCheckoutPath,
+			SourceWorkspaceID:  response.Source.SourceWorkspaceID,
 		},
 		Worktrees: convertWorktrees(response.Worktrees),
 	}, nil

package/internal/runner/herdr/herdrcli/testdata/strict-herdr.sh

@@ -162,6 +162,14 @@ case "$#:${1-}:${2-}" in
       *) emit_result pane-close.json ;;
     esac
     ;;
+  7:workspace:create)
+    [ "$3" = --cwd ] || fail "$@"
+    check_absolute_cwd "$4"
+    [ "$5" = --label ] || fail "$@"
+    check_value "$6"
+    [ "$7" = --no-focus ] || fail "$@"
+    emit_result workspace-create.json
+    ;;
   3:workspace:close)
     check_value "$3"
     case "$3" in

package/internal/runner/herdr/herdrcli/testdata/workspace-create.json

@@ -0,0 +1 @@
+{"id":"cli:workspace:create","result":{"root_pane":{"agent_status":"unknown","cwd":"/tmp/relay-flow-herdr-fixture-9wIblp/repo","focused":true,"foreground_cwd":"/tmp/relay-flow-herdr-fixture-9wIblp/repo","pane_id":"w1:p1","revision":0,"scroll":{"max_offset_from_bottom":0,"offset_from_bottom":0,"viewport_rows":40},"tab_id":"w1:t1","terminal_id":"term_65b0ccebd6e821","workspace_id":"w1"},"tab":{"agent_status":"unknown","focused":true,"label":"1","number":1,"pane_count":1,"tab_id":"w1:t1","workspace_id":"w1"},"type":"workspace_created","workspace":{"active_tab_id":"w1:t1","agent_status":"unknown","focused":true,"label":"payments","number":1,"pane_count":1,"tab_count":1,"workspace_id":"w1"}}}

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

@@ -14,6 +14,7 @@ import (
 
 	"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"
@@ -333,6 +334,24 @@ func TestClientRepoRegistrationFieldsUsesGetThenPost(t *testing.T) {
 	}
 }
 
+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

@@ -118,6 +118,18 @@ func (c *Client) ListWorkflows(ctx context.Context) ([]*workflow.Workflow, error
 	return out, nil
 }
 
+// ListWorkflowSummaries returns one additive summary row per workflow. The
+// server computes all rows in one query boundary; a server without the
+// optional capability still returns definitions, which are decoded as rows
+// with zero execution counts.
+func (c *Client) ListWorkflowSummaries(ctx context.Context) ([]WorkflowSummary, error) {
+	var out []WorkflowSummary
+	if err := c.call(ctx, http.MethodGet, "/workflows?summary=1", nil, &out); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 // GetWorkflow returns one workflow by name.
 func (c *Client) GetWorkflow(ctx context.Context, name string) (*workflow.Workflow, error) {
 	var wf workflow.Workflow
@@ -127,6 +139,15 @@ func (c *Client) GetWorkflow(ctx context.Context, name string) (*workflow.Workfl
 	return &wf, nil
 }
 
+// GetWorkflowDetail returns a definition and a small recent-run summary.
+func (c *Client) GetWorkflowDetail(ctx context.Context, name string) (WorkflowDetail, error) {
+	var out WorkflowDetail
+	if err := c.call(ctx, http.MethodGet, "/workflows/"+url.PathEscape(name)+"?detail=1", nil, &out); err != nil {
+		return WorkflowDetail{}, err
+	}
+	return out, nil
+}
+
 // DiscoverRepos returns runner-visible registration candidates.
 func (c *Client) DiscoverRepos(ctx context.Context) ([]runner.RepoCandidate, error) {
 	var out []runner.RepoCandidate
@@ -136,6 +157,16 @@ func (c *Client) DiscoverRepos(ctx context.Context) ([]runner.RepoCandidate, err
 	return out, nil
 }
 
+// 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 {
@@ -262,6 +293,13 @@ func (c *Client) ListRuns(ctx context.Context, filter run.Filter) ([]run.Run, er
 	if filter.Ticket != "" {
 		q.Set("ticket", filter.Ticket)
 	}
+	if filter.Active != nil {
+		if *filter.Active {
+			q.Set("active", "1")
+		} else {
+			q.Set("active", "0")
+		}
+	}
 	path := "/runs"
 	if s := q.Encode(); s != "" {
 		path += "?" + s
@@ -281,3 +319,14 @@ func (c *Client) GetRunByTicket(ctx context.Context, ticket string) (run.Run, er
 	}
 	return out, nil
 }
+
+// GetRunDetailByTicket returns the additive run inspection response. Existing
+// callers should continue using GetRunByTicket when they only need lifecycle
+// fields.
+func (c *Client) GetRunDetailByTicket(ctx context.Context, ticket string) (run.RunDetail, error) {
+	var out run.RunDetail
+	if err := c.call(ctx, http.MethodGet, "/runs/by-ticket/"+url.PathEscape(ticket), nil, &out); err != nil {
+		return run.RunDetail{}, err
+	}
+	return out, nil
+}

package/internal/server/fixture_test.go

@@ -40,6 +40,8 @@ type fakeServices struct {
 	restartErr         error
 	restarts           []string
 	registrationValues []config.RawValues
+	ensureRepoCalls    []runner.RepoCandidate
+	ensureRepoErr      error
 }
 
 func (f *fakeServices) SubmitWorkflow(_ context.Context, yaml []byte) (*workflow.Workflow, error) {
@@ -155,6 +157,11 @@ func (f *fakeServices) DiscoverRepos(context.Context) ([]runner.RepoCandidate, e
 	return []runner.RepoCandidate{{Name: "payments", Path: "/srv/payments"}}, 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