relay-flow 0.2.4-alpha → 0.2.6-alpha

package/internal/runner/orca/orca_test.go

@@ -39,9 +39,10 @@ func TestSanitizeErr(t *testing.T) {
 
 // fakeCLI is the orcacli.Client seam used by the Orca runner tests.
 type fakeCLI struct {
-	repos     []orcacli.Repo
-	worktrees []orcacli.Worktree
-	terminals map[string]orcacli.Terminal
+	repos           []orcacli.Repo
+	worktrees       []orcacli.Worktree
+	terminals       map[string]orcacli.Terminal
+	listedTerminals []orcacli.Terminal
 
 	createdBaseBranch string
 	createdParent     string
@@ -82,7 +83,7 @@ func (f *fakeCLI) ShowTerminal(_ context.Context, handle string) (orcacli.Termin
 }
 func (f *fakeCLI) SendTerminal(context.Context, string, string) error { return nil }
 func (f *fakeCLI) ListTerminals(context.Context, string) ([]orcacli.Terminal, error) {
-	return nil, nil
+	return f.listedTerminals, nil
 }
 func (f *fakeCLI) CreateTerminal(_ context.Context, _ string, title, command string) (string, error) {
 	f.createN++
@@ -157,6 +158,34 @@ func TestSetEnvironmentStatus(t *testing.T) {
 	}
 }
 
+func TestDiscoverTerminalByStableTitle(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-other", Title: "PAY-1:other", Connected: true},
+			{Handle: "term-node", Title: "PAY-1:implement", Connected: true},
+		},
+	}
+	a, err := New(fx, config.RawValues{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	discoverer, ok := a.(runner.TerminalDiscoverer)
+	if !ok {
+		t.Fatal("Orca runner does not expose recovery terminal discovery")
+	}
+	got, found, err := discoverer.DiscoverTerminal(context.Background(), runner.RunSpec{
+		RepoName: "app", RepoPath: "/srv/app", TicketKey: "PAY-1",
+	}, "PAY-1:implement")
+	if err != nil || !found || got.ID != "term-node" || got.Title != "PAY-1:implement" {
+		t.Fatalf("DiscoverTerminal = %+v, %v, %v", got, found, err)
+	}
+	if fx.createN != 0 {
+		t.Fatalf("terminal discovery created a terminal: %d", fx.createN)
+	}
+}
+
 func TestFindTerminalUsesPersistedID(t *testing.T) {
 	fx := &fakeCLI{terminals: map[string]orcacli.Terminal{
 		"term-stored": {Handle: "term-stored", Title: "PAY-1:implement", Connected: true},

package/internal/runner/runner.go

@@ -56,6 +56,14 @@ type RunSpec struct {
 //
 // Terminal titles are stable and minimal: only "<ticket>:<node>" — never
 // nodeVisitID, workflow name, agent name, or other changing metadata.
+// TerminalDiscoverer is an optional recovery capability. It discovers a
+// currently live run-owned terminal by its stable title without creating a
+// terminal or changing runner state. The core Runner contract remains
+// unchanged for adapters that do not support title discovery.
+type TerminalDiscoverer interface {
+	DiscoverTerminal(ctx context.Context, spec RunSpec, title string) (Terminal, bool, error)
+}
+
 type Runner interface {
 	DiscoverRepos(ctx context.Context) ([]RepoCandidate, error)
 	ValidateRepo(ctx context.Context, name, path string) error

package/internal/task/beads/agent_env_test.go

@@ -0,0 +1,52 @@
+package beads
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/task"
+)
+
+// TestAgentEnvSelectsRegisteredWorkspace asserts that a repo-bound Beads
+// system exposes the configured workspace to agent processes and neutralizes
+// ambient Beads selectors, mirroring the adapter's own child-command
+// isolation.
+func TestAgentEnvSelectsRegisteredWorkspace(t *testing.T) {
+	installRepoCompositionFakeBD(t)
+	root := t.TempDir()
+	codePath := filepath.Join(root, "code", "payments")
+	beadsDir := filepath.Join(root, "beads", "payments", ".beads")
+	for _, path := range []string{codePath, beadsDir} {
+		if err := os.MkdirAll(path, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	sys, err := newSystem(context.Background(), task.RepoSpec{
+		Name: "payments", Path: codePath,
+		RepoConfig: config.RawValues{"beadsDir": beadsDir},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	provider, ok := sys.(task.AgentEnvironment)
+	if !ok {
+		t.Fatal("Beads system does not expose task.AgentEnvironment")
+	}
+	canonical, err := canonicalBeadsDir(beadsDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := map[string]string{
+		"BEADS_DIR": canonical,
+		"BEADS_DB":  "",
+		"BD_DB":     "",
+	}
+	if got := provider.AgentEnv(); !reflect.DeepEqual(got, want) {
+		t.Fatalf("AgentEnv() = %#v, want %#v", got, want)
+	}
+}

package/internal/task/beads/beads.go

@@ -83,8 +83,19 @@ func DefaultConfig() config.RawValues {
 
 func init() {
 	task.Register("beads", task.Factory{
-		RequiredRepoKeys:   func() []string { return []string{"beadsDir"} },
-		TaskScopeKey:       beadsTaskScopeKey,
+		RequiredRepoKeys: func() []string { return []string{"beadsDir"} },
+		TaskScopeKey:     beadsTaskScopeKey,
+		RegistrationKey: func(spec task.RepoRegistrationSpec) (string, error) {
+			label, err := RepositoryLabel(spec.Name)
+			if err != nil {
+				return "", err
+			}
+			scope, err := beadsTaskScopeKey(spec.RootConfig, spec.RepoConfig)
+			if err != nil {
+				return "", err
+			}
+			return scope + "\x00" + label, nil
+		},
 		Auth:               beadsAuth,
 		DefaultConfig:      DefaultConfig,
 		ValidateTextConfig: validateTextConfig,
@@ -98,16 +109,70 @@ const (
 	statusOpen       = "open"
 	statusInProgress = "in_progress"
 	statusClosed     = "closed"
+
+	repositoryLabelPrefix = "repo:"
+	maxRepositoryLabelLen = 255
 )
 
+var repositoryNamePattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]*$`)
+
+// RepositoryLabel derives the reserved Beads label used to isolate one
+// registered code repository from other repositories sharing a workspace.
+// Repository names are normalized to lower case so labels remain stable and
+// two names that differ only by case cannot claim the same Beads issues.
+func RepositoryLabel(name string) (string, error) {
+	if name == "" || strings.TrimSpace(name) != name {
+		return "", errors.New("repository name must be non-empty and must not have surrounding whitespace")
+	}
+	if !repositoryNamePattern.MatchString(name) {
+		return "", fmt.Errorf("repository name %q cannot derive a Beads label; use only letters, numbers, '.', '_' or '-'", name)
+	}
+	label := repositoryLabelPrefix + strings.ToLower(name)
+	if len(label) > maxRepositoryLabelLen {
+		return "", fmt.Errorf("repository name %q derives Beads label of %d characters; maximum is %d", name, len(label), maxRepositoryLabelLen)
+	}
+	return label, nil
+}
+
+func hasRepositoryLabel(labels []string, want string) bool {
+	if want == "" {
+		return false
+	}
+	found := ""
+	count := 0
+	for _, label := range labels {
+		if !strings.HasPrefix(label, repositoryLabelPrefix) {
+			continue
+		}
+		count++
+		found = label
+	}
+	return count == 1 && found == want
+}
+
 // system is one repo-bound Beads task system. Its CLI client serializes
 // commands for the selected workspace, making the system safe for concurrent
 // Repo Poller and durable-activity use.
 type system struct {
-	cli       bdcli.Client
-	mailboxMu sync.Mutex
-	base      config.RawValues
-	effective Config
+	cli             bdcli.Client
+	repositoryLabel string
+	mailboxMu       sync.Mutex
+	base            config.RawValues
+	effective       Config
+	beadsDir        string
+}
+
+// AgentEnv returns the Beads selector environment an agent process needs to
+// address the registered workspace. The configured workspace is the sole
+// BEADS_DIR value; the other selectors are emitted empty so an ambient
+// BEADS_DB or BD_DB cannot redirect the agent's bd commands. This mirrors the
+// adapter's own child-process isolation in bdcli.
+func (s *system) AgentEnv() map[string]string {
+	return map[string]string{
+		"BEADS_DIR": s.beadsDir,
+		"BEADS_DB":  "",
+		"BD_DB":     "",
+	}
 }
 
 // beadsTaskScopeKey returns the canonical physical Beads workspace. The
@@ -157,6 +222,10 @@ func newSystem(ctx context.Context, spec task.RepoSpec) (task.System, error) {
 	if strings.TrimSpace(spec.Name) == "" {
 		return nil, errors.New("beads: repo name is required")
 	}
+	repositoryLabel, err := RepositoryLabel(spec.Name)
+	if err != nil {
+		return nil, fmt.Errorf("beads repo %q: %w", spec.Name, err)
+	}
 	// Validate the repo-scoped key before merging with root values. This keeps a
 	// root beadsDir from silently satisfying repository registration.
 	beadsDir, err := beadsTaskScopeKey(spec.RootConfig, spec.RepoConfig)
@@ -175,7 +244,13 @@ func newSystem(ctx context.Context, spec task.RepoSpec) (task.System, error) {
 	if err := cli.Probe(ctx); err != nil {
 		return nil, fmt.Errorf("beads repo %q probe: %w", spec.Name, err)
 	}
-	return &system{cli: cli, base: merged, effective: cfg}, nil
+	return &system{
+		cli:             cli,
+		repositoryLabel: repositoryLabel,
+		base:            merged,
+		effective:       cfg,
+		beadsDir:        beadsDir,
+	}, nil
 }
 
 func decodeConfig(raw config.RawValues) (Config, error) {
@@ -275,6 +350,11 @@ func (s *system) Poll(ctx context.Context) ([]task.Ticket, error) {
 		if strings.TrimSpace(issue.Parent) != "" {
 			continue
 		}
+		// Missing and ambiguous repository labels are deliberately ignored before
+		// the normalized ticket reaches workflow matching or routing.
+		if !hasRepositoryLabel(issue.Labels, s.repositoryLabel) {
+			continue
+		}
 		tickets = append(tickets, issueToTicket(issue))
 	}
 	return tickets, nil

package/internal/task/beads/beads_test.go

@@ -194,17 +194,86 @@ func TestExtractWorkflowClaimsKeepsOnlyWorkflowLabels(t *testing.T) {
 	}
 }
 
+func TestRepositoryLabelIsStableAndValidated(t *testing.T) {
+	got, err := RepositoryLabel("Payments_API")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != "repo:payments_api" {
+		t.Fatalf("RepositoryLabel = %q, want repo:payments_api", got)
+	}
+	for _, name := range []string{"", " payments", "payments/api", "payments api"} {
+		if _, err := RepositoryLabel(name); err == nil {
+			t.Fatalf("RepositoryLabel accepted invalid name %q", name)
+		}
+	}
+}
+
+func TestRepositoryLabelEnforcesMaximumLength(t *testing.T) {
+	validName := strings.Repeat("a", 250)
+	label, err := RepositoryLabel(validName)
+	if err != nil {
+		t.Fatalf("maximum-length repository name rejected: %v", err)
+	}
+	if len(label) != maxRepositoryLabelLen {
+		t.Fatalf("maximum-length label has length %d, want %d", len(label), maxRepositoryLabelLen)
+	}
+
+	tooLong := strings.Repeat("a", 251)
+	if _, err := RepositoryLabel(tooLong); err == nil || !strings.Contains(err.Error(), "maximum is 255") {
+		t.Fatalf("overlong repository name error = %v, want the 255-character validation", err)
+	}
+}
+
+func TestRegistrationKeyAndNewSystemRejectOverlongRepositoryName(t *testing.T) {
+	name := strings.Repeat("a", 251)
+	workspace := t.TempDir()
+	if _, err := task.RegistrationKey("beads", task.RepoRegistrationSpec{
+		Name:       name,
+		RepoConfig: config.RawValues{"beadsDir": workspace},
+	}); err == nil {
+		t.Fatal("registration identity accepted an overlong repository name")
+	}
+
+	_, err := newSystem(context.Background(), task.RepoSpec{
+		Name:       name,
+		Path:       t.TempDir(),
+		RepoConfig: config.RawValues{"beadsDir": filepath.Join(workspace, "missing")},
+	})
+	if err == nil || !strings.Contains(err.Error(), "maximum is 255") {
+		t.Fatalf("newSystem overlong-name error = %v, want the label validation before workspace probing", err)
+	}
+}
+
+func TestPollFiltersMissingOtherAndAmbiguousRepositoryLabels(t *testing.T) {
+	fake := &pollClient{ready: []bdcli.Issue{
+		{ID: "payments-1", Title: "payments", Labels: []string{"repo:payments", "wf:implementation"}},
+		{ID: "unowned-1", Title: "unowned", Labels: []string{"wf:implementation"}},
+		{ID: "platform-1", Title: "platform", Labels: []string{"repo:platform", "wf:implementation"}},
+		{ID: "ambiguous-1", Title: "ambiguous", Labels: []string{"repo:payments", "repo:platform", "wf:implementation"}},
+		{ID: "duplicate-1", Title: "duplicate", Labels: []string{"repo:payments", "repo:payments"}},
+	}}
+	got, err := (&system{cli: fake, repositoryLabel: "repo:payments"}).Poll(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 1 || got[0].ID != "payments-1" {
+		t.Fatalf("Poll = %+v, want only the payments-labelled parent", got)
+	}
+	if got[0].WorkflowClaims[0] != "wf:implementation" {
+		t.Fatalf("workflow labels were not retained after repository filtering: %+v", got[0])
+	}
+}
+
 func TestPollDeduplicatesReadyAndClaimedParentsByIssueID(t *testing.T) {
-	ready := bdcli.Issue{ID: "demo-a1b2", Title: "ready copy", Status: "open", IssueType: "epic"}
-	claimedDuplicate := bdcli.Issue{ID: "demo-a1b2", Title: "claimed copy", Status: "in_progress", IssueType: "epic", Labels: []string{"wf:implementation"}}
-	claimedOnly := bdcli.Issue{ID: "demo-c3d4", Title: "claimed only", Status: "blocked", IssueType: "task", Labels: []string{"wf:review"}}
+	ready := bdcli.Issue{ID: "demo-a1b2", Title: "ready copy", Status: "open", IssueType: "epic", Labels: []string{"repo:payments"}}
+	claimedDuplicate := bdcli.Issue{ID: "demo-a1b2", Title: "claimed copy", Status: "in_progress", IssueType: "epic", Labels: []string{"repo:payments", "wf:implementation"}}
+	claimedOnly := bdcli.Issue{ID: "demo-c3d4", Title: "claimed only", Status: "blocked", IssueType: "task", Labels: []string{"repo:payments", "wf:review"}}
 	fake := &pollClient{
 		ready:   []bdcli.Issue{ready},
 		claimed: []bdcli.Issue{claimedDuplicate, claimedOnly},
 	}
-	sys := &system{cli: fake}
-
-	got, err := sys.Poll(context.Background())
+	got, err := (&system{cli: fake, repositoryLabel: "repo:payments"}).Poll(context.Background())
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -230,10 +299,10 @@ func TestPollDeduplicatesReadyAndClaimedParentsByIssueID(t *testing.T) {
 }
 
 func TestNormalizedChildIsExcludedFromPolling(t *testing.T) {
-	parent := bdcli.Issue{ID: "demo-parent", Title: "parent", Status: "open", IssueType: "epic"}
-	child := bdcli.Issue{ID: "demo-parent.1", Title: "demo-parent:implement", Status: "open", IssueType: "task", Parent: "demo-parent"}
+	parent := bdcli.Issue{ID: "demo-parent", Title: "parent", Status: "open", IssueType: "epic", Labels: []string{"repo:payments"}}
+	child := bdcli.Issue{ID: "demo-parent.1", Title: "demo-parent:implement", Status: "open", IssueType: "task", Parent: "demo-parent", Labels: []string{"repo:payments"}}
 	fake := &pollClient{ready: []bdcli.Issue{child, parent}, claimed: []bdcli.Issue{child}}
-	got, err := (&system{cli: fake}).Poll(context.Background())
+	got, err := (&system{cli: fake, repositoryLabel: "repo:payments"}).Poll(context.Background())
 	if err != nil {
 		t.Fatal(err)
 	}

package/internal/task/beads/repo_composition_test.go

@@ -99,7 +99,7 @@ func TestBeadsRepoRegistrationUsesIndependentSystemsAndPollers(t *testing.T) {
 	assertBDInvocationReachedRepoAndWorkspace(t, logPath, platformPath, platformBeads)
 }
 
-func TestBeadsRepoRegistrationRejectsSharedCanonicalWorkspace(t *testing.T) {
+func TestBeadsRepoRegistrationAllowsSharedCanonicalWorkspaceWithDistinctLabels(t *testing.T) {
 	root := t.TempDir()
 	installRepoCompositionFakeBD(t)
 	configPath := filepath.Join(root, "config.yaml")
@@ -135,11 +135,55 @@ func TestBeadsRepoRegistrationRejectsSharedCanonicalWorkspace(t *testing.T) {
 	if _, err := svc.Register(context.Background(), repo.RegisterInput{
 		Name: "platform", Path: secondPath,
 		TaskConfig: config.RawValues{"beadsDir": filepath.Join(workspace, ".")},
+	}); err != nil {
+		t.Fatalf("second repo sharing canonical beadsDir with a distinct label was rejected: %v", err)
+	}
+	if len(svc.Registry().List()) != 2 {
+		t.Fatalf("registry after shared workspace registration = %d, want 2", len(svc.Registry().List()))
+	}
+}
+
+func TestBeadsRepoRegistrationRejectsRepositoryLabelCollision(t *testing.T) {
+	root := t.TempDir()
+	installRepoCompositionFakeBD(t)
+	configPath := filepath.Join(root, "config.yaml")
+	if err := config.SaveMachine(configPath, &config.Machine{
+		TaskPlugin: "beads", RunnerPlugin: "orca", HarnessPlugin: "opencode",
+		Repos: map[string]config.Repo{},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	firstPath := filepath.Join(root, "code", "payments")
+	secondPath := filepath.Join(root, "code", "PAYMENTS")
+	workspace := filepath.Join(root, "beads", "shared", ".beads")
+	for _, path := range []string{firstPath, secondPath, workspace} {
+		if err := os.MkdirAll(path, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	svc := repo.NewService(repo.ServiceConfig{
+		ConfigPath: configPath,
+		TaskPlugin: "beads",
+		Runner:     &compositionRunner{},
+		Harness:    &compositionHarness{},
+		Active:     &compositionActive{},
+		Workflows:  &compositionWorkflowRefs{},
+	})
+	if _, err := svc.Register(context.Background(), repo.RegisterInput{
+		Name: "payments", Path: firstPath,
+		TaskConfig: config.RawValues{"beadsDir": workspace},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := svc.Register(context.Background(), repo.RegisterInput{
+		Name: "PAYMENTS", Path: secondPath,
+		TaskConfig: config.RawValues{"beadsDir": workspace},
 	}); err == nil {
-		t.Fatal("second repo sharing canonical beadsDir was accepted")
+		t.Fatal("repository label collision was accepted")
 	}
 	if len(svc.Registry().List()) != 1 {
-		t.Fatalf("registry after duplicate scope rejection = %d, want 1", len(svc.Registry().List()))
+		t.Fatalf("registry after label collision = %d, want 1", len(svc.Registry().List()))
 	}
 }
 

package/internal/task/factory.go

@@ -20,13 +20,25 @@ type RepoSpec struct {
 	RepoConfig config.RawValues
 }
 
+// RepoRegistrationSpec carries the values a task plugin may need to derive a
+// registration identity. Unlike RepoSpec, it does not include the code path
+// or construct a task System.
+type RepoRegistrationSpec struct {
+	Name       string
+	RootConfig config.RawValues
+	RepoConfig config.RawValues
+}
+
 // Factory constructs a task System. RequiredRepoKeys returns the explicit
 // repo YAML keys needed at registration. TaskScopeKey derives an opaque
 // canonical physical task scope (such as Jira site/project/component) used
-// to reject duplicate scope registration.
+// to reject duplicate scope registration. RegistrationKey optionally derives
+// the complete registration identity when a plugin permits sharing a
+// physical scope with distinct logical repositories.
 type Factory struct {
 	RequiredRepoKeys   func() []string
 	TaskScopeKey       func(rootConfig, repoConfig config.RawValues) (string, error)
+	RegistrationKey    func(RepoRegistrationSpec) (string, error)
 	Auth               func(context.Context, []string, io.Reader) error
 	DefaultConfig      func() config.RawValues
 	ValidateTextConfig func(config.RawValues) error
@@ -122,7 +134,10 @@ func RequiredRepoKeys(name string) ([]string, error) {
 	return f.RequiredRepoKeys(), nil
 }
 
-// TaskScopeKey derives the canonical task scope for the named plugin.
+// TaskScopeKey derives the canonical physical task scope for the named
+// plugin. It is retained separately from RegistrationKey so callers that
+// need provider workspace identity do not have to know about logical repo
+// ownership.
 func TaskScopeKey(name string, rootConfig, repoConfig config.RawValues) (string, error) {
 	f, err := lookup(name)
 	if err != nil {
@@ -131,6 +146,20 @@ func TaskScopeKey(name string, rootConfig, repoConfig config.RawValues) (string,
 	return f.TaskScopeKey(rootConfig, repoConfig)
 }
 
+// RegistrationKey derives the identity used to reject conflicting repo
+// registrations. Plugins that do not provide a custom key fall back to their
+// physical TaskScopeKey, preserving the original duplicate-scope behavior.
+func RegistrationKey(name string, spec RepoRegistrationSpec) (string, error) {
+	f, err := lookup(name)
+	if err != nil {
+		return "", err
+	}
+	if f.RegistrationKey != nil {
+		return f.RegistrationKey(spec)
+	}
+	return f.TaskScopeKey(spec.RootConfig, spec.RepoConfig)
+}
+
 // ValidateName returns an error listing registered names when name is not
 // a registered plugin. Used by `relay-flow init` to reject unknown plugin
 // selections without constructing a System.

package/internal/task/task.go

@@ -99,6 +99,16 @@ type System interface {
 	ResetForRecovery(ctx context.Context, parent TicketRef, mailboxes []Mailbox, taskConfig config.RawValues) error
 }
 
+// AgentEnvironment is an optional adapter capability. It returns the
+// task-system workspace environment an agent process must receive so agent
+// task commands address the same workspace as relay-flow. Values are
+// workspace selectors only, never credentials; an empty value explicitly
+// neutralizes an ambient selector. Core forwards the map through the harness
+// launch spec without learning adapter vocabulary.
+type AgentEnvironment interface {
+	AgentEnv() map[string]string
+}
+
 // RestartPreparer is an optional adapter capability used only by explicit
 // run restarts. It reopens relay-owned mailbox state while preserving all
 // comments, labels, and descriptions. A human-owned incompatible state must

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-flow",
-  "version": "0.2.4-alpha",
+  "version": "0.2.6-alpha",
   "description": "Graph-based agent workflow engine — tracker-agnostic, pluggable runners",
   "bin": {
     "relay-flow": "./bin/relay-flow.js",