relay-flow 0.2.5-alpha → 0.2.7-alpha

package/internal/execution/goworkflows/node_runtime_test.go

@@ -9,6 +9,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/rajpopat27/relay-flow/internal/config"
 	"github.com/rajpopat27/relay-flow/internal/harness"
 	"github.com/rajpopat27/relay-flow/internal/repo"
 	"github.com/rajpopat27/relay-flow/internal/run"
@@ -210,7 +211,7 @@ func TestEnsureNodeRuntimeUsesDirectIDsAndFallsBackFresh(t *testing.T) {
 	}); err != nil {
 		t.Fatal(err)
 	}
-	a := &Activities{Runner: fr, Harness: fh, Runs: p}
+	a := &Activities{Repos: runtimeTestRepos(&runtimeTestTaskSystem{}), Runner: fr, Harness: fh, Runs: p}
 	nw := run.NodeWork{Work: run.Work{RunID: id, Repo: "payments", Workflow: "basic", Parent: task.TicketRef{Key: "PAY-101"}}, Node: "implement", NodeVisitID: "visit-2"}
 	spec := harness.LaunchSpec{RunID: id, NodeVisitID: "visit-2", RepoName: "payments", Workflow: "basic", Ticket: "PAY-101", Node: "implement", Agent: "build", Title: "PAY-101:implement", Prompt: "work", NudgePrompt: "custom instructions"}
 	if err := a.EnsureNodeRuntime(ctx, nw, "/srv/payments", spec, NodeRuntime{NodeVisitID: "visit-2"}); err != nil {
@@ -259,8 +260,8 @@ func TestEnsureNodeRuntimeInitialLaunchAppendsCustomInstructions(t *testing.T) {
 	}
 	fh := &runtimeTestHarness{}
 	fr := &runtimeTestRunner{}
-	a := &Activities{Runner: fr, Harness: fh, Runs: p}
-	nw := run.NodeWork{Work: run.Work{RunID: id}, Node: "implement", NodeVisitID: "visit-first"}
+	a := &Activities{Repos: runtimeTestRepos(&runtimeTestTaskSystem{}), Runner: fr, Harness: fh, Runs: p}
+	nw := run.NodeWork{Work: run.Work{RunID: id, Repo: "payments"}, Node: "implement", NodeVisitID: "visit-first"}
 	spec := harness.LaunchSpec{RunID: id, NodeVisitID: "visit-first", Node: "implement", NodeType: workflow.NodeHITL, Agent: "build", Prompt: "standard prompt", NudgePrompt: "custom instructions"}
 	if err := a.EnsureNodeRuntime(ctx, nw, "", spec, NodeRuntime{}); err != nil {
 		t.Fatal(err)
@@ -273,6 +274,63 @@ func TestEnsureNodeRuntimeInitialLaunchAppendsCustomInstructions(t *testing.T) {
 	}
 }
 
+// TestEnsureNodeRuntimeSuppliesTaskSystemAgentEnv asserts the repo's task
+// system supplies the agent workspace environment at launch time, so the
+// harness/runner command addresses the same workspace as relay-flow. Adapters
+// without the optional capability supply nothing.
+func TestEnsureNodeRuntimeSuppliesTaskSystemAgentEnv(t *testing.T) {
+	ctx := context.Background()
+	db := openProjectionDB(t, filepath.Join(t.TempDir(), "state.db"))
+	defer db.Close()
+	p := &RunProjection{DB: db}
+	if err := p.migrate(); err != nil {
+		t.Fatal(err)
+	}
+	id := run.ID("payments/basic/PAY-105")
+	if err := p.insertStart(ctx, run.Start{ID: id, Repo: "payments", Workflow: workflow.Workflow{Name: "basic"}, Ticket: task.TicketRef{ID: "5", Key: "PAY-105"}}, time.Now().UTC()); err != nil {
+		t.Fatal(err)
+	}
+	if err := p.updateNodeRuntimeVisit(ctx, id, "implement", "visit-first"); err != nil {
+		t.Fatal(err)
+	}
+	want := map[string]string{"BEADS_DIR": "/var/lib/beads/payments/.beads", "BEADS_DB": "", "BD_DB": ""}
+	fh := &runtimeTestHarness{}
+	a := &Activities{
+		Repos:   runtimeTestRepos(&runtimeTestTaskSystem{agentEnv: want}),
+		Runner:  &runtimeTestRunner{},
+		Harness: fh,
+		Runs:    p,
+	}
+	nw := run.NodeWork{Work: run.Work{RunID: id, Repo: "payments", Workflow: "basic", Parent: task.TicketRef{Key: "PAY-105"}}, Node: "implement", NodeVisitID: "visit-first"}
+	spec := harness.LaunchSpec{RunID: id, NodeVisitID: "visit-first", RepoName: "payments", Node: "implement", Agent: "build", Title: "PAY-105:implement"}
+	if err := a.EnsureNodeRuntime(ctx, nw, "/srv/payments", spec, NodeRuntime{}); err != nil {
+		t.Fatal(err)
+	}
+	if len(fh.taskEnvs) != 1 || !reflect.DeepEqual(fh.taskEnvs[0], want) {
+		t.Fatalf("launch TaskEnv = %#v, want [%#v]", fh.taskEnvs, want)
+	}
+
+	// An adapter without the optional capability supplies no environment.
+	plain := &runtimeTestHarness{}
+	b := &Activities{
+		Repos:   runtimeTestRepos(&runtimeTestPlainTaskSystem{System: &runtimeTestTaskSystem{}}),
+		Runner:  &runtimeTestRunner{},
+		Harness: plain,
+		Runs:    p,
+	}
+	if err := p.updateNodeRuntimeVisit(ctx, id, "review", "visit-review"); err != nil {
+		t.Fatal(err)
+	}
+	nw.Node, nw.NodeVisitID = "review", "visit-review"
+	spec.Node, spec.NodeVisitID, spec.Title = "review", "visit-review", "PAY-105:review"
+	if err := b.EnsureNodeRuntime(ctx, nw, "/srv/payments", spec, NodeRuntime{}); err != nil {
+		t.Fatal(err)
+	}
+	if len(plain.taskEnvs) != 1 || plain.taskEnvs[0] != nil {
+		t.Fatalf("TaskEnv without a configured workspace = %#v, want [nil]", plain.taskEnvs)
+	}
+}
+
 func TestEnsureNodeRuntimeSendFailureClosesLiveTerminal(t *testing.T) {
 	ctx := context.Background()
 	db := openProjectionDB(t, filepath.Join(t.TempDir(), "state.db"))
@@ -293,7 +351,7 @@ func TestEnsureNodeRuntimeSendFailureClosesLiveTerminal(t *testing.T) {
 	}
 	fr := &runtimeTestRunner{live: true, sendErr: errors.New("send failed")}
 	fh := &runtimeTestHarness{}
-	a := &Activities{Runner: fr, Harness: fh, Runs: p}
+	a := &Activities{Repos: runtimeTestRepos(&runtimeTestTaskSystem{}), Runner: fr, Harness: fh, Runs: p}
 	nw := run.NodeWork{Work: run.Work{RunID: id, Repo: "payments", Workflow: "basic", Parent: task.TicketRef{Key: "PAY-102"}}, Node: "implement", NodeVisitID: "visit-new", Mailbox: task.Mailbox{Key: "PAY-234", Node: "implement"}}
 	spec := harness.LaunchSpec{RunID: id, NodeVisitID: "visit-new", Node: "implement", Agent: "build", Title: "PAY-102:implement", Prompt: "work", NudgePrompt: "Read the latest review feedback."}
 	if err := a.EnsureNodeRuntime(ctx, nw, "/srv/payments", spec, NodeRuntime{RunID: id, Node: "implement", TerminalID: "live-old", SessionID: "session-old", NodeVisitID: "visit-old"}); err != nil {
@@ -499,6 +557,7 @@ type runtimeTestHarness struct {
 	prompts    []string
 	resumeIDs  []string
 	rendered   []harness.PromptKind
+	taskEnvs   []map[string]string
 }
 
 func (h *runtimeTestHarness) RenderPrompt(kind harness.PromptKind, _ harness.PromptData, nudge string) (string, error) {
@@ -522,9 +581,59 @@ func (h *runtimeTestHarness) BuildCommand(spec harness.LaunchSpec) (runner.Comma
 	h.buildCalls++
 	h.prompts = append(h.prompts, spec.Prompt)
 	h.resumeIDs = append(h.resumeIDs, spec.ResumeID)
+	h.taskEnvs = append(h.taskEnvs, spec.TaskEnv)
 	return runner.Command{Executable: "opencode", Args: []string{spec.ResumeID}}, nil
 }
 
+// runtimeTestTaskSystem is a repo-bound task system stub. Only the optional
+// task.AgentEnvironment capability is exercised here; every other method is an
+// unused stub for the node runtime tests.
+type runtimeTestTaskSystem struct {
+	agentEnv map[string]string
+}
+
+func (s *runtimeTestTaskSystem) AgentEnv() map[string]string { return s.agentEnv }
+
+func (*runtimeTestTaskSystem) Poll(context.Context) ([]task.Ticket, error) { return nil, nil }
+func (*runtimeTestTaskSystem) CompileFilter(config.RawValues) (func(task.Ticket) bool, error) {
+	return func(task.Ticket) bool { return true }, nil
+}
+func (*runtimeTestTaskSystem) Claim(context.Context, task.TicketRef, string) error { return nil }
+func (*runtimeTestTaskSystem) ValidateConfig(context.Context, config.RawValues, map[string]config.RawValues) error {
+	return nil
+}
+func (*runtimeTestTaskSystem) RenderText(task.TextKind, task.TextData) (string, error) {
+	return "", nil
+}
+func (*runtimeTestTaskSystem) EnsureMailboxes(context.Context, task.TicketRef, string, []task.MailboxSpec) (map[string]task.Mailbox, error) {
+	return map[string]task.Mailbox{}, nil
+}
+func (*runtimeTestTaskSystem) ApplyTaskConfig(context.Context, task.Target, config.RawValues) error {
+	return nil
+}
+func (*runtimeTestTaskSystem) CompleteMailbox(context.Context, task.Mailbox) error { return nil }
+func (*runtimeTestTaskSystem) HasComment(context.Context, task.Target, string) (bool, error) {
+	return false, nil
+}
+func (*runtimeTestTaskSystem) Comment(context.Context, task.Target, string, string) error {
+	return nil
+}
+func (*runtimeTestTaskSystem) ResetForRecovery(context.Context, task.TicketRef, []task.Mailbox, config.RawValues) error {
+	return nil
+}
+
+// runtimeTestPlainTaskSystem forwards the task.System contract without
+// exposing the optional AgentEnvironment capability.
+type runtimeTestPlainTaskSystem struct {
+	task.System
+}
+
+func runtimeTestRepos(sys task.System) *repo.Registry {
+	reg := &repo.Registry{}
+	reg.Replace(&repo.Repo{Name: "payments", Path: "/srv/payments", TaskSystem: sys})
+	return reg
+}
+
 func openProjectionDB(t *testing.T, path string) *sql.DB {
 	t.Helper()
 	db, err := sql.Open("sqlite", path)

package/internal/execution/temporal/activities.go

@@ -40,6 +40,21 @@ func (a *Activities) taskSystem(repoName string) (task.System, error) {
 	return rp.TaskSystem, nil
 }
 
+// agentEnv returns the repo task system's agent workspace environment, or nil
+// when the adapter exposes none. It is resolved at launch time so no workspace
+// value is carried in durable workflow history.
+func (a *Activities) agentEnv(repoName string) (map[string]string, error) {
+	sys, err := a.taskSystem(repoName)
+	if err != nil {
+		return nil, err
+	}
+	provider, ok := sys.(task.AgentEnvironment)
+	if !ok {
+		return nil, nil
+	}
+	return provider.AgentEnv(), nil
+}
+
 func (a *Activities) runSpec(w run.Work) runner.RunSpec {
 	return runner.RunSpec{
 		RunID:     w.RunID,
@@ -228,6 +243,10 @@ func (a *Activities) EnsureNodeRuntime(ctx context.Context, nw run.NodeWork, rep
 	if err != nil {
 		return NodeRuntime{}, err
 	}
+	spec.TaskEnv, err = a.agentEnv(nw.Repo)
+	if err != nil {
+		return NodeRuntime{}, err
+	}
 	cmd, err := a.Harness.BuildCommand(spec)
 	if err != nil {
 		return NodeRuntime{}, err

package/internal/harness/harness.go

@@ -56,6 +56,11 @@ type LaunchSpec struct {
 	PromptData  PromptData
 	NextSteps   []workflow.Route
 	ResumeID    string
+	// TaskEnv is the task-system-owned workspace environment for the agent
+	// process, supplied by the repo's task adapter. The harness adds it to the
+	// launch command environment without interpreting it; relay-flow's own
+	// variables always win on conflict.
+	TaskEnv map[string]string
 }
 
 type Harness interface {

package/internal/harness/opencode/opencode.go

@@ -3,7 +3,8 @@
 // their stable <ticket>:<node> title, and builds the structured command
 // the runner executes. The OpenCode runtime plugin (TypeScript, under
 // plugin/) owns message parsing, title pinning, nudge-on-invalid for
-// agent nodes, silence for HITL, and exact-report JSON retry with the
+// agent nodes and for non-empty invalid HITL output, silence for missing
+// or aborted HITL output, and exact-report JSON retry with the
 // shared backoff constants mirrored in TypeScript.
 package opencode
 
@@ -186,7 +187,13 @@ func (h *Harness) BuildCommand(spec harness.LaunchSpec) (runner.Command, error)
 	if err != nil {
 		return runner.Command{}, err
 	}
-	env := map[string]string{
+	env := map[string]string{}
+	// Task-system workspace values are applied first so relay-flow's own
+	// variables always win on conflict.
+	for key, value := range spec.TaskEnv {
+		env[key] = value
+	}
+	for key, value := range map[string]string{
 		"RELAY_FLOW_HOME":            root,
 		"RELAY_FLOW_RUN_ID":          string(spec.RunID),
 		"RELAY_FLOW_WORKFLOW":        spec.Workflow,
@@ -196,6 +203,8 @@ func (h *Harness) BuildCommand(spec harness.LaunchSpec) (runner.Command, error)
 		"RELAY_FLOW_NODE_TYPE":       string(spec.NodeType),
 		"RELAY_FLOW_NUDGE_PROMPT":    spec.NudgePrompt,
 		"RELAY_FLOW_NEXT_STEPS_JSON": string(nextSteps),
+	} {
+		env[key] = value
 	}
 	args := []string{}
 	if spec.ResumeID != "" {

package/internal/harness/opencode/opencode_test.go

@@ -14,7 +14,7 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
-const configuredPlugin = "relay-flow-plugin@0.2.5-alpha"
+const configuredPlugin = "relay-flow-plugin@0.2.7-alpha"
 
 func TestBuildCommandArgv(t *testing.T) {
 	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")

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.5-alpha"
+const relayFlowPlugin = "relay-flow-plugin@0.2.7-alpha"
 
 type jsoncToken struct {
 	kind       byte

package/internal/harness/opencode/task_env_test.go

@@ -0,0 +1,57 @@
+package opencode_test
+
+import (
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/harness"
+	"github.com/rajpopat27/relay-flow/internal/harness/opencode"
+)
+
+// TestBuildCommandCarriesTaskSystemEnvironment asserts the task-system
+// workspace environment reaches the runner command so agent task commands
+// address the same workspace as relay-flow, and that relay-flow's own
+// variables cannot be overwritten by the task system.
+func TestBuildCommandCarriesTaskSystemEnvironment(t *testing.T) {
+	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")
+
+	cmd, err := opencode.New().BuildCommand(harness.LaunchSpec{
+		Agent:  "build",
+		Node:   "implement",
+		Prompt: "implement the ticket",
+		TaskEnv: map[string]string{
+			"BEADS_DIR":       "/var/lib/beads/payments/.beads",
+			"BEADS_DB":        "",
+			"BD_DB":           "",
+			"RELAY_FLOW_NODE": "hijacked",
+		},
+	})
+	if err != nil {
+		t.Fatalf("BuildCommand: %v", err)
+	}
+	if cmd.Env["BEADS_DIR"] != "/var/lib/beads/payments/.beads" {
+		t.Fatalf("BEADS_DIR = %q", cmd.Env["BEADS_DIR"])
+	}
+	for _, key := range []string{"BEADS_DB", "BD_DB"} {
+		value, ok := cmd.Env[key]
+		if !ok || value != "" {
+			t.Fatalf("%s = %q, present=%v; want empty selector", key, value, ok)
+		}
+	}
+	if cmd.Env["RELAY_FLOW_NODE"] != "implement" {
+		t.Fatalf("RELAY_FLOW_NODE = %q, want implement", cmd.Env["RELAY_FLOW_NODE"])
+	}
+}
+
+// TestBuildCommandWithoutTaskEnvKeepsRelayVariablesOnly asserts an adapter
+// that exposes no workspace environment adds nothing to the command.
+func TestBuildCommandWithoutTaskEnvKeepsRelayVariablesOnly(t *testing.T) {
+	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")
+
+	cmd, err := opencode.New().BuildCommand(harness.LaunchSpec{Agent: "build", Prompt: "work"})
+	if err != nil {
+		t.Fatalf("BuildCommand: %v", err)
+	}
+	if len(cmd.Env) != 9 {
+		t.Fatalf("Env = %#v, want only the nine relay-flow variables", cmd.Env)
+	}
+}

package/internal/harness/pi/pi.go

@@ -189,7 +189,13 @@ func (*Harness) BuildCommand(spec harness.LaunchSpec) (runner.Command, error) {
 	if err != nil {
 		return runner.Command{}, err
 	}
-	env := map[string]string{
+	env := map[string]string{}
+	// Task-system workspace values are applied first so relay-flow's own
+	// variables always win on conflict.
+	for key, value := range spec.TaskEnv {
+		env[key] = value
+	}
+	for key, value := range map[string]string{
 		"RELAY_FLOW_HOME":            root,
 		"RELAY_FLOW_RUN_ID":          string(spec.RunID),
 		"RELAY_FLOW_WORKFLOW":        spec.Workflow,
@@ -199,6 +205,8 @@ func (*Harness) BuildCommand(spec harness.LaunchSpec) (runner.Command, error) {
 		"RELAY_FLOW_NODE_TYPE":       string(spec.NodeType),
 		"RELAY_FLOW_NUDGE_PROMPT":    spec.NudgePrompt,
 		"RELAY_FLOW_NEXT_STEPS_JSON": string(nextSteps),
+	} {
+		env[key] = value
 	}
 	args := []string{"--name", spec.Title}
 	if spec.Agent != "default" {

package/internal/harness/pi/task_env_test.go

@@ -0,0 +1,51 @@
+package pi
+
+import (
+	"testing"
+)
+
+// TestBuildCommandCarriesTaskSystemEnvironment asserts the task-system
+// workspace environment reaches the runner command so agent task commands
+// address the same workspace as relay-flow, and that relay-flow's own
+// variables cannot be overwritten by the task system.
+func TestBuildCommandCarriesTaskSystemEnvironment(t *testing.T) {
+	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")
+
+	spec := launchSpec(t)
+	spec.TaskEnv = map[string]string{
+		"BEADS_DIR":       "/var/lib/beads/payments/.beads",
+		"BEADS_DB":        "",
+		"BD_DB":           "",
+		"RELAY_FLOW_NODE": "hijacked",
+	}
+	cmd, err := (&Harness{}).BuildCommand(spec)
+	if err != nil {
+		t.Fatalf("BuildCommand: %v", err)
+	}
+	if cmd.Env["BEADS_DIR"] != "/var/lib/beads/payments/.beads" {
+		t.Fatalf("BEADS_DIR = %q", cmd.Env["BEADS_DIR"])
+	}
+	for _, key := range []string{"BEADS_DB", "BD_DB"} {
+		value, ok := cmd.Env[key]
+		if !ok || value != "" {
+			t.Fatalf("%s = %q, present=%v; want empty selector", key, value, ok)
+		}
+	}
+	if cmd.Env["RELAY_FLOW_NODE"] != spec.Node {
+		t.Fatalf("RELAY_FLOW_NODE = %q, want %q", cmd.Env["RELAY_FLOW_NODE"], spec.Node)
+	}
+}
+
+// TestBuildCommandWithoutTaskEnvKeepsRelayVariablesOnly asserts an adapter
+// that exposes no workspace environment adds nothing to the command.
+func TestBuildCommandWithoutTaskEnvKeepsRelayVariablesOnly(t *testing.T) {
+	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")
+
+	cmd, err := (&Harness{}).BuildCommand(launchSpec(t))
+	if err != nil {
+		t.Fatalf("BuildCommand: %v", err)
+	}
+	if len(cmd.Env) != 9 {
+		t.Fatalf("Env = %#v, want only the nine relay-flow variables", cmd.Env)
+	}
+}

package/internal/repo/service.go

@@ -86,8 +86,8 @@ type RegisterInput struct {
 }
 
 // Register validates the runner repo, required task values, task-system
-// connectivity, duplicate names, canonical paths, and duplicate canonical
-// task scope before atomically writing machine config.
+// 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) {
 	if input.Name == "" {
 		return Info{}, fmt.Errorf("repo: name is required")
@@ -116,19 +116,29 @@ 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)
 		}
 	}
-	// Duplicate canonical task scope: compute this repo's scope and compare
-	// against every registered repo's scope.
-	newScope, err := task.TaskScopeKey(s.taskPlugin, cfg.TaskConfig, input.TaskConfig)
+	// 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
+	// share one workspace safely.
+	newScope, err := task.RegistrationKey(s.taskPlugin, task.RepoRegistrationSpec{
+		Name:       input.Name,
+		RootConfig: cfg.TaskConfig,
+		RepoConfig: input.TaskConfig,
+	})
 	if err != nil {
 		return Info{}, fmt.Errorf("repo %q: %w", input.Name, err)
 	}
 	for name, r := range cfg.Repos {
-		scope, err := task.TaskScopeKey(s.taskPlugin, cfg.TaskConfig, r.TaskConfig)
+		scope, err := task.RegistrationKey(s.taskPlugin, task.RepoRegistrationSpec{
+			Name:       name,
+			RootConfig: cfg.TaskConfig,
+			RepoConfig: r.TaskConfig,
+		})
 		if err != nil {
-			return Info{}, fmt.Errorf("repo %q: derive scope of registered repo %q: %w", input.Name, name, err)
+			return Info{}, fmt.Errorf("repo %q: derive registration identity of registered repo %q: %w", input.Name, name, err)
 		}
 		if scope == newScope {
-			return Info{}, fmt.Errorf("repo %q: task scope already used by repo %q", input.Name, name)
+			return Info{}, fmt.Errorf("repo %q: task registration identity already used by repo %q", input.Name, name)
 		}
 	}
 	// Runner validates the repo.

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