relay-flow 0.2.7-alpha → 0.2.9-alpha

package/internal/harness/opencode/repo_setup.go

@@ -10,7 +10,7 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/config"
 )
 
-const relayFlowPlugin = "relay-flow-plugin@0.2.7-alpha"
+const relayFlowPlugin = "relay-flow-plugin@0.2.9-alpha"
 
 type jsoncToken struct {
 	kind       byte

package/internal/harness/pi/prompt_test.go

@@ -23,13 +23,13 @@ func TestPiRenderPromptSubstitutesInitialAndFeedbackData(t *testing.T) {
 		NextSteps:       "review (when: ready)",
 		Mailbox:         "PAY-234",
 	}
-	nudge := "nudge {{taskSystem}}|{{ticket}}|{{workflow}}|{{repo}}|{{node}}|{{nextSteps}}"
+	nudge := "nudge {{taskSystem}}|{{ticket}}|{{workflow}}|{{repo}}|{{node}}|{{mailbox}}|{{nextSteps}}"
 
 	initial, err := h.RenderPrompt(harness.PromptInitial, data, nudge)
 	if err != nil {
 		t.Fatalf("RenderPrompt(initial): %v", err)
 	}
-	wantInitial := "Task system: jira\nUse the jira tools to read the parent ticket PAY-101.\n\nYour mailbox is PAY-234. Read its description and comments for node instructions and feedback.\n\nKeep the summary brief, and make the feedback as detailed and actionable as possible for the next agent.\n\nnudge jira|PAY-101|basicFlow|payments|implement|review (when: ready)"
+	wantInitial := "Task system: jira\nUse the jira tools to read the parent ticket PAY-101.\n\nYour mailbox is PAY-234. Read its description and comments for node instructions and feedback.\n\nKeep the summary brief, and make the feedback as detailed and actionable as possible for the next agent.\n\nnudge jira|PAY-101|basicFlow|payments|implement|PAY-234|review (when: ready)"
 	if initial != wantInitial {
 		t.Fatalf("initial prompt = %q, want %q", initial, wantInitial)
 	}
@@ -38,7 +38,7 @@ func TestPiRenderPromptSubstitutesInitialAndFeedbackData(t *testing.T) {
 	if err != nil {
 		t.Fatalf("RenderPrompt(feedback): %v", err)
 	}
-	wantFeedback := "New feedback was added to the comments section of your mailbox subtask PAY-234. Read it.\n\nnudge jira|PAY-101|basicFlow|payments|implement|review (when: ready)"
+	wantFeedback := "New feedback was added to the comments section of your mailbox subtask PAY-234. Read it.\n\nnudge jira|PAY-101|basicFlow|payments|implement|PAY-234|review (when: ready)"
 	if feedback != wantFeedback {
 		t.Fatalf("feedback prompt = %q, want %q", feedback, wantFeedback)
 	}

package/internal/repo/service.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"path/filepath"
+	"strings"
 
 	"github.com/rajpopat27/relay-flow/internal/config"
 	"github.com/rajpopat27/relay-flow/internal/harness"
@@ -70,6 +71,25 @@ func (s *Service) Discover(ctx context.Context) ([]runner.RepoCandidate, error)
 	return s.runner.DiscoverRepos(ctx)
 }
 
+// EnsureRepo makes the runner resource for a repository available without
+// changing relay-flow's machine configuration. Runner adapters that expose
+// RepoRegistrar perform their idempotent external provisioning; other
+// runners validate the repository through the existing read-only contract.
+func (s *Service) EnsureRepo(ctx context.Context, name, path string) error {
+	name = strings.TrimSpace(name)
+	path = strings.TrimSpace(path)
+	if name == "" {
+		return fmt.Errorf("repo: name is required")
+	}
+	if path == "" {
+		return fmt.Errorf("repo %q: path is required", name)
+	}
+	if registrar, ok := s.runner.(runner.RepoRegistrar); ok {
+		return registrar.EnsureRepo(ctx, name, path)
+	}
+	return s.runner.ValidateRepo(ctx, name, path)
+}
+
 // RequiredRepoKeys delegates to the task factory's method of the same name.
 func (s *Service) RequiredRepoKeys() []string {
 	keys, err := task.RequiredRepoKeys(s.taskPlugin)
@@ -79,6 +99,12 @@ func (s *Service) RequiredRepoKeys() []string {
 	return keys
 }
 
+// RegistrationFields returns task-plugin-owned registration prompts and
+// choices. Core repo management does not interpret the returned keys.
+func (s *Service) RegistrationFields(ctx context.Context, values config.RawValues) ([]task.RegistrationField, error) {
+	return task.RegistrationFields(ctx, s.taskPlugin, values)
+}
+
 type RegisterInput struct {
 	Name       string
 	Path       string
@@ -89,9 +115,14 @@ type RegisterInput struct {
 // connectivity, duplicate names, canonical paths, and the task plugin's
 // registration identity before atomically writing machine config.
 func (s *Service) Register(ctx context.Context, input RegisterInput) (Info, error) {
+	input.Name = strings.TrimSpace(input.Name)
+	input.Path = strings.TrimSpace(input.Path)
 	if input.Name == "" {
 		return Info{}, fmt.Errorf("repo: name is required")
 	}
+	if input.Path == "" {
+		return Info{}, fmt.Errorf("repo %q: path is required", input.Name)
+	}
 	cfg, err := config.LoadMachine(s.cfgPath)
 	if err != nil {
 		return Info{}, err
@@ -116,6 +147,13 @@ func (s *Service) Register(ctx context.Context, input RegisterInput) (Info, erro
 			return Info{}, fmt.Errorf("repo %q: required task config key %q is missing", input.Name, k)
 		}
 	}
+	if err := task.ValidateRegistration(ctx, s.taskPlugin, task.RepoRegistrationSpec{
+		Name:       input.Name,
+		RootConfig: cfg.TaskConfig,
+		RepoConfig: input.TaskConfig,
+	}); err != nil {
+		return Info{}, fmt.Errorf("repo %q: %w", input.Name, err)
+	}
 	// Duplicate registration identity: compute this repo's identity and compare
 	// against every registered repo. Most plugins use their physical task scope;
 	// Beads includes its derived repository label so distinct repositories may
@@ -141,8 +179,10 @@ func (s *Service) Register(ctx context.Context, input RegisterInput) (Info, erro
 			return Info{}, fmt.Errorf("repo %q: task registration identity already used by repo %q", input.Name, name)
 		}
 	}
-	// Runner validates the repo.
-	if err := s.runner.ValidateRepo(ctx, input.Name, input.Path); err != nil {
+	// Runner validates or provisions the repo, depending on the adapter
+	// capability. Provisioning is idempotent so explicit registration and the
+	// interactive Add action share one runner-owned path.
+	if err := s.EnsureRepo(ctx, input.Name, input.Path); err != nil {
 		return Info{}, fmt.Errorf("repo %q: runner validation: %w", input.Name, err)
 	}
 	// Task-system connectivity: construct the repo-bound System.
@@ -232,5 +272,9 @@ func canonicalPath(p string) string {
 	if err != nil {
 		return filepath.Clean(p)
 	}
-	return filepath.Clean(abs)
+	abs = filepath.Clean(abs)
+	if resolved, err := filepath.EvalSymlinks(abs); err == nil {
+		return filepath.Clean(resolved)
+	}
+	return abs
 }

package/internal/repo/service_test.go

@@ -23,6 +23,17 @@ type fakeRunnerDiscovery struct {
 	validErr   error
 }
 
+type fakeRunnerRegistrar struct {
+	*fakeRunnerDiscovery
+	ensureErr   error
+	ensureCalls []runner.RepoCandidate
+}
+
+func (f *fakeRunnerRegistrar) EnsureRepo(_ context.Context, name, path string) error {
+	f.ensureCalls = append(f.ensureCalls, runner.RepoCandidate{Name: name, Path: path})
+	return f.ensureErr
+}
+
 func (f *fakeRunnerDiscovery) DiscoverRepos(context.Context) ([]runner.RepoCandidate, error) {
 	return f.candidates, nil
 }
@@ -228,6 +239,17 @@ func TestRegisterValidatesRunnerRepo(t *testing.T) {
 	}
 }
 
+func TestRegisterUsesRunnerRepoProvisioningCapability(t *testing.T) {
+	rn := &fakeRunnerRegistrar{fakeRunnerDiscovery: &fakeRunnerDiscovery{validErr: errInvalidRepo{}}}
+	fx := newServiceFixture(t, rn)
+	if _, err := fx.svc.Register(context.Background(), repo.RegisterInput{Name: "payments", Path: "/srv/payments", TaskConfig: config.RawValues{"project": "P", "component": "c"}}); err != nil {
+		t.Fatal(err)
+	}
+	if len(rn.ensureCalls) != 1 || rn.ensureCalls[0] != (runner.RepoCandidate{Name: "payments", Path: "/srv/payments"}) {
+		t.Fatalf("EnsureRepo calls = %+v", rn.ensureCalls)
+	}
+}
+
 func TestRegisterValidatesTaskConnectivity(t *testing.T) {
 	// The task factory's New is invoked to validate connectivity; its error
 	// must reject registration before persisting.
@@ -264,7 +286,10 @@ func (errInvalidRepo) Error() string { return "invalid repo" }
 
 func TestRegisterAtomicallyPersists(t *testing.T) {
 	fx := newServiceFixture(t, &fakeRunnerDiscovery{})
-	if _, err := fx.svc.Register(context.Background(), repo.RegisterInput{Name: "payments", Path: "/srv/payments", TaskConfig: config.RawValues{"project": "PAY", "component": "api"}}); err != nil {
+	statusDefaults := map[string]any{"start": "Open", "work": "Working", "end": "Closed"}
+	if _, err := fx.svc.Register(context.Background(), repo.RegisterInput{Name: "payments", Path: "/srv/payments", TaskConfig: config.RawValues{
+		"project": "PAY", "component": "api", "statusDefaults": statusDefaults,
+	}}); err != nil {
 		t.Fatal(err)
 	}
 	cfg, err := config.LoadMachine(fx.cfgPath)
@@ -278,6 +303,16 @@ func TestRegisterAtomicallyPersists(t *testing.T) {
 	if r.TaskConfig["project"] != "PAY" {
 		t.Fatalf("repo taskConfig not persisted: %+v", r.TaskConfig)
 	}
+	var gotDefaults map[string]any
+	switch values := r.TaskConfig["statusDefaults"].(type) {
+	case map[string]any:
+		gotDefaults = values
+	case config.RawValues:
+		gotDefaults = map[string]any(values)
+	}
+	if gotDefaults == nil || gotDefaults["start"] != "Open" || gotDefaults["work"] != "Working" || gotDefaults["end"] != "Closed" {
+		t.Fatalf("repo statusDefaults not persisted: %#v", r.TaskConfig["statusDefaults"])
+	}
 }
 
 func TestRegisterSetsUpHarnessRepo(t *testing.T) {

package/internal/runner/herdr/herdr.go

@@ -91,11 +91,15 @@ func (a *adapter) DiscoverRepos(ctx context.Context) ([]runner.RepoCandidate, er
 	}
 	candidates := make(map[string]runner.RepoCandidate)
 	for _, workspace := range snapshot.Workspaces {
-		root := normalizePath(workspace.Worktree.RepoRoot)
-		if root == "" {
+		candidate, ok, err := a.workspaceRepository(ctx, workspace, snapshot.Panes)
+		if err != nil {
+			logOutcome("discover-repos", "error")
+			return nil, err
+		}
+		if !ok {
 			continue
 		}
-		candidates[root] = runner.RepoCandidate{Name: workspace.Worktree.RepoName, Path: root}
+		candidates[canonicalCandidatePath(candidate.Path)] = candidate
 	}
 	out := make([]runner.RepoCandidate, 0, len(candidates))
 	for _, candidate := range candidates {
@@ -111,8 +115,102 @@ func (a *adapter) DiscoverRepos(ctx context.Context) ([]runner.RepoCandidate, er
 	return out, nil
 }
 
+// workspaceRepository resolves the Git identity of a workspace. Herdr's
+// snapshot includes worktree metadata for linked worktrees, but plain source
+// workspaces may omit the worktree object; their pane CWD is the supported
+// lookup handle for worktree list.
+func (a *adapter) workspaceRepository(ctx context.Context, workspace herdrcli.Workspace, panes []herdrcli.Pane) (runner.RepoCandidate, bool, error) {
+	if root := normalizePath(workspace.Worktree.RepoRoot); root != "" {
+		name := workspace.Worktree.RepoName
+		if name == "" {
+			name = workspace.Label
+		}
+		return runner.RepoCandidate{Name: name, Path: root}, true, nil
+	}
+	for _, pane := range panes {
+		if pane.WorkspaceID != workspace.ID || !filepath.IsAbs(strings.TrimSpace(pane.CWD)) {
+			continue
+		}
+		listing, err := a.cli.WorktreeList(ctx, pane.CWD)
+		if errors.Is(err, herdrcli.ErrNotGitWorktree) {
+			continue
+		}
+		if err != nil {
+			return runner.RepoCandidate{}, false, err
+		}
+		root := normalizePath(listing.Source.RepoRoot)
+		if root == "" {
+			continue
+		}
+		name := listing.Source.RepoName
+		if name == "" {
+			name = workspace.Label
+		}
+		return runner.RepoCandidate{Name: name, Path: root}, true, nil
+	}
+	return runner.RepoCandidate{}, false, nil
+}
+
+func canonicalCandidatePath(path string) string {
+	if normalized := normalizePath(path); normalized != "" {
+		return normalized
+	}
+	return path
+}
+
+// EnsureRepo opens a source repository as a Herdr workspace when it is not
+// already open. WorktreeList is the source of truth for both the repository
+// root and the source workspace handle; it is checked before workspace create
+// so repeated registration remains idempotent even when snapshots omit
+// worktree metadata for plain source workspaces.
+func (a *adapter) EnsureRepo(ctx context.Context, name, path string) error {
+	attrs := []any{"repo", name}
+	logCall("ensure-repo", attrs...)
+	root := normalizePath(path)
+	if root == "" {
+		logOutcome("ensure-repo", "error", attrs...)
+		return fmt.Errorf("herdr: repository %q has an empty path", name)
+	}
+	listing, err := a.cli.WorktreeList(ctx, root)
+	if err != nil {
+		logOutcome("ensure-repo", "error", attrs...)
+		return err
+	}
+	if reported := normalizePath(listing.Source.RepoRoot); reported != root {
+		logOutcome("ensure-repo", "error", attrs...)
+		return fmt.Errorf("herdr: repository %q path %q is not its repository root %q", name, path, reported)
+	}
+	if hasOpenSourceWorkspace(listing) {
+		logOutcome("ensure-repo", "exists", attrs...)
+		return nil
+	}
+	registrar, ok := a.cli.(herdrcli.RepositoryRegistrar)
+	if !ok {
+		logOutcome("ensure-repo", "error", attrs...)
+		return fmt.Errorf("herdr: repository workspace provisioning is unavailable")
+	}
+	if _, err := registrar.CreateWorkspace(ctx, root, name); err != nil {
+		logOutcome("ensure-repo", "error", attrs...)
+		return err
+	}
+	logOutcome("ensure-repo", "created", attrs...)
+	return nil
+}
+
+func hasOpenSourceWorkspace(listing herdrcli.WorktreeListing) bool {
+	if listing.Source.SourceWorkspaceID != "" {
+		return true
+	}
+	for _, worktree := range listing.Worktrees {
+		if !worktree.IsLinked && worktree.OpenWorkspaceID != "" {
+			return true
+		}
+	}
+	return false
+}
+
 // ValidateRepo verifies the registered path is the root of a Git repository
-// Herdr can manage. Registration needs no Herdr workspace and creates none.
+// Herdr can manage without creating a workspace.
 func (a *adapter) ValidateRepo(ctx context.Context, name, path string) error {
 	logCall("validate-repo", "repo", name)
 	registered := normalizePath(path)
@@ -590,3 +688,4 @@ func normalizePath(path string) string {
 }
 
 var _ runner.Runner = (*adapter)(nil)
+var _ runner.RepoRegistrar = (*adapter)(nil)

package/internal/runner/herdr/herdr_test.go

@@ -29,8 +29,11 @@ type fakeClient struct {
 	openWorkspace herdrcli.Workspace
 	openErr       error
 
-	createWorkspace herdrcli.Workspace
-	createErr       error
+	createWorkspace        herdrcli.Workspace
+	createErr              error
+	createdSourceWorkspace herdrcli.Workspace
+	createdSourceErr       error
+	workspaceCreateCalls   []worktreeCall
 
 	tabs    []herdrcli.Tab
 	tabsErr error
@@ -95,6 +98,13 @@ func (f *fakeClient) WorktreeOpen(_ context.Context, repoPath, branch, label str
 	return f.openWorkspace, f.openErr
 }
 
+func (f *fakeClient) CreateWorkspace(_ context.Context, repoPath, label string) (herdrcli.Workspace, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.workspaceCreateCalls = append(f.workspaceCreateCalls, worktreeCall{RepoPath: repoPath, Label: label})
+	return f.createdSourceWorkspace, f.createdSourceErr
+}
+
 func (f *fakeClient) CreateTab(_ context.Context, workspaceID, cwd, label string) (herdrcli.Tab, herdrcli.Pane, error) {
 	f.mu.Lock()
 	defer f.mu.Unlock()
@@ -240,6 +250,26 @@ func TestDiscoverReposDeduplicatesRepositoryRoots(t *testing.T) {
 	}
 }
 
+func TestDiscoverReposResolvesPlainSourceWorkspaceFromPaneCWD(t *testing.T) {
+	cli := &fakeClient{
+		snapshot: herdrcli.Snapshot{
+			Workspaces: []herdrcli.Workspace{{ID: "w-source", Label: "payments"}},
+			Panes:      []herdrcli.Pane{{ID: "w-source:p1", WorkspaceID: "w-source", CWD: repoPath}},
+		},
+		listing: herdrcli.WorktreeListing{
+			Source: herdrcli.WorktreeSource{RepoName: "payments", RepoRoot: repoPath, SourceCheckoutPath: repoPath},
+		},
+	}
+	got, err := newAdapter(cli).DiscoverRepos(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []runner.RepoCandidate{{Name: "payments", Path: repoPath}}
+	if len(got) != 1 || got[0] != want[0] {
+		t.Fatalf("DiscoverRepos = %+v, want %+v", got, want)
+	}
+}
+
 func TestValidateRepoAcceptsRepositoryRootAndRejectsInnerPaths(t *testing.T) {
 	cli := &fakeClient{listing: herdrcli.WorktreeListing{
 		Source: herdrcli.WorktreeSource{RepoName: "payments", RepoRoot: repoPath, SourceCheckoutPath: repoPath},
@@ -278,6 +308,46 @@ func TestValidateRepoCreatesNothing(t *testing.T) {
 	}
 }
 
+func TestEnsureRepoReusesAnOpenSourceWorkspace(t *testing.T) {
+	cli := &fakeClient{
+		listing:  herdrcli.WorktreeListing{Source: herdrcli.WorktreeSource{RepoRoot: repoPath, SourceWorkspaceID: "w-source"}},
+		snapshot: herdrcli.Snapshot{Workspaces: []herdrcli.Workspace{{ID: "w-source"}}},
+	}
+	a := newAdapter(cli)
+	if err := a.EnsureRepo(context.Background(), "payments", repoPath); err != nil {
+		t.Fatal(err)
+	}
+	if err := a.EnsureRepo(context.Background(), "payments", repoPath); err != nil {
+		t.Fatal(err)
+	}
+	if len(cli.workspaceCreateCalls) != 0 {
+		t.Fatalf("CreateWorkspace calls = %+v, want none", cli.workspaceCreateCalls)
+	}
+}
+
+func TestEnsureRepoOpensMissingSourceWorkspace(t *testing.T) {
+	cli := &fakeClient{
+		listing:                herdrcli.WorktreeListing{Source: herdrcli.WorktreeSource{RepoRoot: repoPath}},
+		createdSourceWorkspace: herdrcli.Workspace{ID: "source-workspace"},
+	}
+	if err := newAdapter(cli).EnsureRepo(context.Background(), "payments", repoPath); err != nil {
+		t.Fatal(err)
+	}
+	if len(cli.workspaceCreateCalls) != 1 || cli.workspaceCreateCalls[0] != (worktreeCall{RepoPath: repoPath, Label: "payments"}) {
+		t.Fatalf("CreateWorkspace calls = %+v", cli.workspaceCreateCalls)
+	}
+}
+
+func TestEnsureRepoPropagatesSourceWorkspaceFailure(t *testing.T) {
+	cli := &fakeClient{
+		listing:          herdrcli.WorktreeListing{Source: herdrcli.WorktreeSource{RepoRoot: repoPath}},
+		createdSourceErr: errors.New("herdr unavailable"),
+	}
+	if err := newAdapter(cli).EnsureRepo(context.Background(), "payments", repoPath); err == nil || !strings.Contains(err.Error(), "herdr unavailable") {
+		t.Fatalf("EnsureRepo error = %v, want workspace creation failure", err)
+	}
+}
+
 // --- Environment ---
 
 func TestEnsureEnvironmentReusesExistingTicketWorktree(t *testing.T) {

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

@@ -35,6 +35,13 @@ type Client interface {
 	CloseWorkspace(ctx context.Context, workspaceID string) error
 }
 
+// RepositoryRegistrar is the optional repository-workspace provisioning seam
+// used by the Herdr runner adapter. It remains separate from Client so
+// existing runtime-only test clients do not need to implement registration.
+type RepositoryRegistrar interface {
+	CreateWorkspace(ctx context.Context, cwd, label string) (Workspace, error)
+}
+
 // Options selects the Herdr session or explicit socket used by the CLI.
 type Options struct {
 	Session    string
@@ -51,9 +58,10 @@ func New(options Options) *CLI {
 	return &CLI{options: options}
 }
 
-// WorkspaceWorktree is the Git identity Herdr reports for a workspace. The
-// source checkout of a repository has IsLinked false; every ticket worktree
-// workspace has IsLinked true and the same RepoRoot.
+// WorkspaceWorktree is the Git identity Herdr may report for a workspace.
+// Linked ticket workspaces have IsLinked true and the source RepoRoot. Plain
+// source workspaces can omit this object; callers resolve those through their
+// pane CWD and worktree list.
 type WorkspaceWorktree struct {
 	CheckoutPath string
 	RepoName     string
@@ -82,6 +90,7 @@ type WorktreeSource struct {
 	RepoName           string
 	RepoRoot           string
 	SourceCheckoutPath string
+	SourceWorkspaceID  string
 }
 
 // WorktreeListing is the response of worktree list for one repository.

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

@@ -24,6 +24,9 @@ func TestCLIUsesExactProductionCommandShapes(t *testing.T) {
 	if _, err := cli.WorktreeOpen(ctx, "/work/payments", "PAY-101", "PAY-101"); err != nil {
 		t.Fatalf("WorktreeOpen: %v", err)
 	}
+	if _, err := cli.CreateWorkspace(ctx, "/work/payments", "payments"); err != nil {
+		t.Fatalf("CreateWorkspace: %v", err)
+	}
 	if _, err := cli.WorktreeCreate(ctx, "/work/payments", "PAY-101", "origin/main", "PAY-101"); err != nil {
 		t.Fatalf("WorktreeCreate: %v", err)
 	}
@@ -85,11 +88,19 @@ func TestCLIDecodesCapturedResponseLocations(t *testing.T) {
 		t.Fatalf("Snapshot panes = %+v", snapshot.Panes)
 	}
 
+	sourceWorkspace, err := cli.CreateWorkspace(ctx, "/work/payments", "payments")
+	if err != nil {
+		t.Fatalf("CreateWorkspace: %v", err)
+	}
+	if sourceWorkspace.ID != "w1" || sourceWorkspace.Label != "payments" || sourceWorkspace.Worktree.RepoRoot != "" {
+		t.Fatalf("CreateWorkspace = %+v, want the captured plain source workspace shape", sourceWorkspace)
+	}
+
 	listing, err := cli.WorktreeList(ctx, "/work/payments")
 	if err != nil {
 		t.Fatalf("WorktreeList: %v", err)
 	}
-	if listing.Source.RepoRoot != "/work/payments" || listing.Source.RepoName != "repo" {
+	if listing.Source.RepoRoot != "/work/payments" || listing.Source.RepoName != "repo" || listing.Source.SourceWorkspaceID != "w1" {
 		t.Fatalf("WorktreeList source = %+v", listing.Source)
 	}
 	if len(listing.Worktrees) != 2 {
@@ -231,8 +242,12 @@ func TestCLIRejectsRelativeCWD(t *testing.T) {
 
 func TestStrictFakeHerdrRejectsUnsupportedProductionShapes(t *testing.T) {
 	fake := installStrictFakeHerdr(t)
+	// This test invokes the fake executable directly rather than through CLI,
+	// so provide the same selector environment the production wrapper sets.
+	t.Setenv("HERDR_SESSION", "relay-flow")
+	t.Setenv("HERDR_SOCKET_PATH", "/tmp/relay-flow-herdr.sock")
 	unsupported := [][]string{
-		{"workspace", "create", "--cwd", "/work/payments", "--label", "payments", "--no-focus"},
+		{"workspace", "get", "w2"},
 		{"worktree", "remove", "--workspace", "w2"},
 		{"terminal", "create", "--pane", "w2:p2"},
 		{"pane", "get", "--pane", "w2:p2"},

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"}}}