relay-flow 0.2.8-alpha → 0.2.10-alpha

package/internal/run/detail.go

@@ -0,0 +1,277 @@
+package run
+
+import (
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+// StepStatus is the display-only lifecycle of one recorded node visit. It is
+// deliberately separate from State: State is the execution authority's
+// current run state, while StepStatus describes one historical row in the
+// relay-owned inspection projection.
+type StepStatus string
+
+const (
+	StepPending   StepStatus = "pending"
+	StepRunning   StepStatus = "running"
+	StepWaiting   StepStatus = "waiting"
+	StepSucceeded StepStatus = "succeeded"
+	StepFailed    StepStatus = "failed"
+	StepBlocked   StepStatus = "blocked"
+	StepCanceled  StepStatus = "canceled"
+)
+
+// StepEntry is the small, engine-neutral read model used by run inspection.
+// Sequence is the stable execution order within one attempt. A node visit is
+// identified by NodeVisitID when the node is a work node; lifecycle rows such
+// as start/end may not have one.
+type StepEntry struct {
+	RunID          ID            `json:"runId,omitempty"`
+	Sequence       int64         `json:"sequence"`
+	Node           string        `json:"node"`
+	NodeVisitID    NodeVisitID   `json:"nodeVisitId,omitempty"`
+	NodeType       string        `json:"nodeType,omitempty"`
+	ParentSequence int64         `json:"parentSequence,omitempty"`
+	Depth          int           `json:"depth,omitempty"`
+	Status         StepStatus    `json:"status"`
+	StartedAt      *time.Time    `json:"startedAt,omitempty"`
+	FinishedAt     *time.Time    `json:"finishedAt,omitempty"`
+	Duration       time.Duration `json:"duration,omitempty"`
+	DurationKnown  bool          `json:"durationKnown,omitempty"`
+	Message        string        `json:"message,omitempty"`
+	Route          string        `json:"route,omitempty"`
+	Runtime        string        `json:"runtime,omitempty"`
+	Resource       string        `json:"resource,omitempty"`
+}
+
+// RunConditions are derived from the current run state and retry metadata.
+// They are display data only and do not participate in execution decisions.
+type RunConditions struct {
+	NodeRunning    bool `json:"nodeRunning"`
+	Waiting        bool `json:"waiting"`
+	RetryScheduled bool `json:"retryScheduled"`
+	Completed      bool `json:"completed"`
+	Failed         bool `json:"failed"`
+	Canceled       bool `json:"canceled"`
+}
+
+// RunProgress counts reached visits in the derived timeline. Pending rows are
+// the denominator remainder for an active/waiting run.
+type RunProgress struct {
+	Completed int `json:"completed"`
+	Total     int `json:"total"`
+	Pending   int `json:"pending"`
+}
+
+// ResourceDuration is an optional display aggregation. Known is false when
+// executors did not retain resource attribution; zero values with Known=true
+// represent a real zero-duration resource interval.
+type ResourceDuration struct {
+	Known      bool          `json:"known"`
+	Runner     time.Duration `json:"runner,omitempty"`
+	TaskSystem time.Duration `json:"taskSystem,omitempty"`
+	Harness    time.Duration `json:"harness,omitempty"`
+	Other      time.Duration `json:"other,omitempty"`
+}
+
+// RunDetail embeds the original Run value so existing JSON clients that
+// decode a run.Run continue to work when the server adds inspection fields.
+// The remaining fields are read-only relay projection data.
+type RunDetail struct {
+	Run
+	CreatedAt         *time.Time       `json:"createdAt,omitempty"`
+	Conditions        RunConditions    `json:"conditions"`
+	Progress          RunProgress      `json:"progress"`
+	ResourcesDuration ResourceDuration `json:"resourcesDuration"`
+	Steps             []StepEntry      `json:"steps"`
+}
+
+// NewRunDetail creates an empty detail response for a base run. Projection
+// implementations fill Steps and derive the remaining fields.
+func NewRunDetail(r Run) RunDetail {
+	return RunDetail{Run: r, Steps: []StepEntry{}}
+}
+
+// AddPendingNodes adds only pending downstream rows that can be justified by
+// the current run state and selected route. Completed runs intentionally show
+// only actual visits; the static graph is not treated as execution history.
+func (d *RunDetail) AddPendingNodes(wf workflow.Workflow) {
+	if d.State == StateCompleted {
+		return
+	}
+	actual := make(map[string]bool, len(d.Steps))
+	maxSequence := int64(-1)
+	current := d.CurrentNode
+	var currentStep *StepEntry
+	for i := range d.Steps {
+		step := &d.Steps[i]
+		if step.Status == StepPending {
+			continue
+		}
+		actual[step.Node] = true
+		if step.Sequence > maxSequence {
+			maxSequence = step.Sequence
+		}
+		if currentStep == nil || step.Sequence > currentStep.Sequence {
+			currentStep = step
+		}
+	}
+	if current == "" && currentStep != nil {
+		current = currentStep.Node
+	}
+	if current == "" {
+		return
+	}
+
+	candidates := make([]string, 0, 2)
+	addCandidate := func(target string) {
+		if target == "" || actual[target] {
+			return
+		}
+		for _, existing := range candidates {
+			if existing == target {
+				return
+			}
+		}
+		candidates = append(candidates, target)
+	}
+	if currentStep != nil && currentStep.Node == current && currentStep.Route != "" {
+		addCandidate(currentStep.Route)
+	} else if node, ok := wf.Nodes[current]; ok {
+		for _, route := range append(append([]workflow.Route{}, node.OnSuccess...), node.OnFailure...) {
+			addCandidate(route.Target)
+		}
+	}
+
+	added := map[string]bool{}
+	var appendPending func(string, bool)
+	appendPending = func(name string, followSingle bool) {
+		if name == "" || actual[name] || added[name] {
+			return
+		}
+		node, ok := wf.Nodes[name]
+		if !ok {
+			return
+		}
+		added[name] = true
+		nodeType := string(node.Type)
+		if name == workflow.StartNode || name == workflow.EndNode {
+			nodeType = "lifecycle"
+		}
+		maxSequence++
+		d.Steps = append(d.Steps, StepEntry{RunID: d.ID, Sequence: maxSequence,
+			Node: name, NodeType: nodeType, Status: StepPending, Depth: 1})
+		if !followSingle || name == workflow.EndNode {
+			return
+		}
+		routes := append(append([]workflow.Route{}, node.OnSuccess...), node.OnFailure...)
+		if len(routes) == 1 {
+			appendPending(routes[0].Target, true)
+		}
+	}
+	for _, candidate := range candidates {
+		appendPending(candidate, currentStep != nil && currentStep.Node == current && currentStep.Route != "")
+	}
+}
+
+// DeriveInspectionFields fills conditions, progress, and resource durations
+// from the supplied run and step timeline. This helper intentionally reads no
+// executor or task-system state.
+func (d *RunDetail) DeriveInspectionFields(now time.Time) {
+	if now.IsZero() {
+		now = time.Now().UTC()
+	}
+	d.Conditions = RunConditions{
+		NodeRunning:    d.State == StateRunning,
+		Waiting:        d.State == StateWaiting,
+		RetryScheduled: d.Retry != nil,
+		Completed:      d.State == StateCompleted,
+		Failed:         d.State == StateBlocked,
+		Canceled:       d.State == StateCanceled || d.State == StateCanceling,
+	}
+	d.Progress = RunProgress{Total: len(d.Steps)}
+	d.ResourcesDuration = ResourceDuration{}
+	for i, step := range d.Steps {
+		switch step.Status {
+		case StepPending:
+			d.Progress.Pending++
+		default:
+			// Progress counts reached visits, including the current waiting or
+			// blocked visit; pending rows are the denominator remainder.
+			d.Progress.Completed++
+		}
+		duration := step.Duration
+		if duration == 0 && step.StartedAt != nil && step.FinishedAt != nil {
+			duration = step.FinishedAt.Sub(*step.StartedAt)
+			d.Steps[i].DurationKnown = true
+		}
+		if duration == 0 && step.StartedAt != nil && step.FinishedAt == nil &&
+			(step.Status == StepRunning || step.Status == StepWaiting || step.Status == StepBlocked) {
+			duration = now.Sub(*step.StartedAt)
+		}
+		if duration < 0 {
+			duration = 0
+		}
+		if step.Resource != "" {
+			d.ResourcesDuration.Known = true
+		}
+		switch step.Resource {
+		case "runner":
+			d.ResourcesDuration.Runner += duration
+		case "task-system", "taskSystem":
+			d.ResourcesDuration.TaskSystem += duration
+		case "harness":
+			d.ResourcesDuration.Harness += duration
+		case "":
+		default:
+			d.ResourcesDuration.Other += duration
+		}
+	}
+}
+
+// DisplayStatus returns the stable human status vocabulary used by the CLI.
+func (r Run) DisplayStatus() string {
+	switch r.State {
+	case StateCompleted:
+		return "Succeeded"
+	case StateRunning:
+		return "Running"
+	case StateWaiting:
+		return "Waiting"
+	case StateBlocked:
+		return "Failed"
+	case StateCanceled, StateCanceling:
+		return "Canceled"
+	case StateStarting:
+		return "Running"
+	default:
+		return string(r.State)
+	}
+}
+
+// DisplayStatus returns the stable human status vocabulary for a step.
+func (s StepStatus) DisplayStatus() string {
+	switch s {
+	case StepSucceeded:
+		return "Succeeded"
+	case StepRunning:
+		return "Running"
+	case StepWaiting:
+		return "Waiting"
+	case StepFailed, StepBlocked:
+		return "Failed"
+	case StepCanceled:
+		return "Canceled"
+	case StepPending:
+		return "Pending"
+	default:
+		return string(s)
+	}
+}
+
+// IsTerminal reports whether a step has finished and should contribute to
+// progress. It is intentionally local to the display model.
+func (s StepStatus) IsTerminal() bool {
+	return s == StepSucceeded || s == StepFailed || s == StepCanceled
+}

package/internal/run/detail_test.go

@@ -0,0 +1,71 @@
+package run
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+func TestRunDetailDerivationIsRepeatable(t *testing.T) {
+	started := time.Now().UTC().Add(-time.Minute)
+	finished := started.Add(30 * time.Second)
+	detail := NewRunDetail(Run{State: StateWaiting})
+	detail.Steps = []StepEntry{{Status: StepSucceeded, StartedAt: &started, FinishedAt: &finished, Resource: "harness"}}
+	detail.DeriveInspectionFields(time.Now().UTC())
+	first := detail.ResourcesDuration.Harness
+	detail.DeriveInspectionFields(time.Now().UTC())
+	if first <= 0 || detail.ResourcesDuration.Harness != first {
+		t.Fatalf("resource duration changed on repeat: first=%s second=%s", first, detail.ResourcesDuration.Harness)
+	}
+}
+
+func TestCompletedRunDoesNotInventUnvisitedBranchRows(t *testing.T) {
+	detail := NewRunDetail(Run{State: StateCompleted, CurrentNode: workflow.EndNode})
+	detail.Steps = []StepEntry{
+		{Sequence: 0, Node: workflow.StartNode, Status: StepSucceeded},
+		{Sequence: 1, Node: "coding", Status: StepSucceeded},
+		{Sequence: 2, Node: workflow.EndNode, Status: StepSucceeded},
+	}
+	detail.AddPendingNodes(workflow.Workflow{Nodes: map[string]workflow.Node{
+		workflow.StartNode: {}, "coding": {}, "review": {}, workflow.EndNode: {},
+	}})
+	if len(detail.Steps) != 3 {
+		t.Fatalf("completed branch added pending rows: %#v", detail.Steps)
+	}
+}
+
+func TestRunDetailAddsPendingStaticNodesWithoutChangingActualVisits(t *testing.T) {
+	detail := NewRunDetail(Run{State: StateWaiting, CurrentNode: "coding"})
+	detail.Steps = []StepEntry{{Sequence: 0, Node: workflow.StartNode, Status: StepSucceeded, Depth: 1}, {Sequence: 1, Node: "coding", Status: StepWaiting, Depth: 1}}
+	detail.AddPendingNodes(workflow.Workflow{Nodes: map[string]workflow.Node{
+		workflow.StartNode: {}, "coding": {OnSuccess: []workflow.Route{{Target: workflow.EndNode}}}, workflow.EndNode: {}, "review": {},
+	}})
+	detail.DeriveInspectionFields(time.Now().UTC())
+	if len(detail.Steps) != 3 || detail.Steps[2].Status != StepPending || detail.Progress.Pending != 1 || detail.Progress.Total != 3 {
+		t.Fatalf("pending detail = %#v", detail)
+	}
+	if detail.Steps[0].Status != StepSucceeded || detail.Steps[1].Status != StepWaiting {
+		t.Fatalf("actual visits changed: %#v", detail.Steps)
+	}
+}
+
+func TestRunDetailJSONKeepsBaseRunFieldsAndStepIdentity(t *testing.T) {
+	detail := NewRunDetail(Run{ID: "repo/workflow/T-1", State: StateWaiting})
+	detail.Steps = []StepEntry{{RunID: detail.ID, Sequence: 1, Node: "coding", Status: StepWaiting}}
+	raw, err := json.Marshal(detail)
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(raw)
+	for _, want := range []string{`"id":"repo/workflow/T-1"`, `"steps"`, `"node":"coding"`} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("JSON %q missing %s", text, want)
+		}
+	}
+	if !strings.Contains(text, `"runId":"repo/workflow/T-1"`) {
+		t.Fatalf("step identity missing from JSON: %s", text)
+	}
+}

package/internal/run/run.go

@@ -124,6 +124,10 @@ type ReportAck struct {
 // its current durable state. Server handlers map it to HTTP 409.
 var ErrRestartConflict = errors.New("restart conflict")
 
+// ErrNotFound identifies a missing durable run in the engine-neutral query
+// boundary. HTTP adapters may map it to their own 404 error type.
+var ErrNotFound = errors.New("run not found")
+
 // NodeRuntimeRegistration binds the OpenCode session emitted for one run/node.
 type NodeRuntimeRegistration struct {
 	RunID     ID     `json:"runId"`

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