relay-flow 0.2.5-alpha → 0.2.6-alpha

package/README.md

@@ -177,7 +177,13 @@ bd init \
 # Example external workspace: /var/lib/beads/payments/.beads
 ```
 
-Register the code repository and its Beads workspace separately. `beadsDir` is required for every Beads repo, must name an existing directory, and is the task scope used to reject duplicate workspace registration:
+For the relay-flow installation used by this repository, the configured Beads workspace is:
+
+```text
+/home/raj/.beads/relay-flow/.beads
+```
+
+Register the code repository and its Beads workspace separately. `beadsDir` is required for every Beads repo and must name an existing directory. It selects the Beads workspace/database; it is not the code repository path or a workflow filter:
 
 ```sh
 # Local/embedded workspace
@@ -193,7 +199,7 @@ relay-flow repo register \
   --set beadsDir=/var/lib/beads/payments/.beads
 ```
 
-The registered `--path` remains the code/runner repository. Every `bd` command runs with that path as its working directory and the configured `beadsDir` as `BEADS_DIR`, even when unrelated Beads selector variables exist in the relay-flow environment. Two repos may register different canonical `beadsDir` values; a second repo pointing at the same workspace is rejected. A Beads prefix such as `payments-...` is optional and only makes issue IDs recognizable—it is not a component, workspace selector, poller selector, or database isolation mechanism.
+The registered `--path` remains the code/runner repository. Every `bd` command runs with that path as its working directory and the configured `beadsDir` as `BEADS_DIR`, even when unrelated Beads selector variables exist in the relay-flow environment. Multiple code repositories may share one Beads/Dolt workspace when their derived repository labels differ. Relay-flow derives one reserved label, `repo:<lowercase-registered-name>`, for each repository; names must use letters, numbers, `.`, `_`, or `-`, and be at most 250 characters so the derived label stays within Beads' 255-character limit. The label is not entered in workflow configuration. A parent must carry exactly one such repository label to be eligible for that repo's poller: missing or ambiguous `repo:` labels are ignored before workflow filters and routing. Workflow ownership labels remain independent `wf:<workflow>` labels. A collision between derived labels in the same workspace is rejected before the second repository is registered. A Beads prefix such as `payments-...` is optional and only makes issue IDs recognizable—it is not a component, workspace selector, poller selector, or database isolation mechanism.
 
 Beads workflow filters are structured and evaluated in relay-flow. For example, `examples/beads-workflow.yaml` uses the Beads status and issue-type fields:
 
@@ -211,7 +217,7 @@ Filter values are exact and are not translated between providers.
 
 The supported Beads status names are `open`, `in_progress`, `blocked`, `deferred`, `hooked`, and `closed`. The claimed-parent poll uses the canonical active set `open,in_progress,blocked,deferred`; it intentionally does not substitute `hooked` for `deferred`. Omitted lifecycle settings move the parent to `in_progress` at `start`, a work-node mailbox to `in_progress`, and the parent to `closed` at `end` — the same shape as Jira, with Beads-native values. Relay-flow creates one Repo Poller per registered repo, not one poller per workflow. Each poll reads ready top-level parents and relay-owned active parents, deduplicates them, and never routes mailbox children. Claims are permanent `wf:<workflow>` labels.
 
-Beads does not need relay-flow credentials or a Beads-specific poller. In server mode, leave Dolt and Beads server setup running outside relay-flow and point each repo at its own `beadsDir`.
+Beads does not need relay-flow credentials or a Beads-specific poller. In server mode, leave Dolt and Beads server setup running outside relay-flow; each registered code repository still supplies its `beadsDir`, and repositories that share that workspace are isolated by their derived `repo:` labels.
 
 ### Submit a workflow
 

package/cmd/relay-flow/beads_composition_test.go

@@ -361,9 +361,9 @@ issue_json() {
   case "$issue" in
     demo-parent)
       if [ -f "$BD_STATE/claimed" ]; then
-        labels='["wf:beadsComposition"]'
+        labels='["repo:payments","wf:beadsComposition"]'
       else
-        labels='[]'
+        labels='["repo:payments"]'
       fi
       printf '[{"id":"demo-parent","title":"Composition parent","status":"%s","issue_type":"epic","priority":1,"labels":%s}]\n' "$status" "$labels"
       ;;
@@ -385,7 +385,7 @@ if [ "$#" -eq 6 ] && [ "$1" = list ] && [ "$2" = --ready ] && [ "$3" = --no-pare
   if [ -f "$BD_STATE/claimed" ]; then
     printf '[]\n'
   else
-    printf '[{"id":"demo-parent","title":"Composition parent","status":"open","issue_type":"epic","priority":1,"labels":[]}]\n'
+    printf '[{"id":"demo-parent","title":"Composition parent","status":"open","issue_type":"epic","priority":1,"labels":["repo:payments"]}]\n'
   fi
   exit 0
 fi

package/examples/beads-workflow.yaml

@@ -4,6 +4,9 @@
 #   relay-flow repo register --name payments --path /work/payments \
 #     --set beadsDir=/work/payments/.beads
 #
+# Relay-flow derives the reserved repo:payments label from the registered
+# repository name. Parents without exactly one matching repo: label are
+# ignored before workflow filters; wf:<workflow> remains a separate claim.
 # The Beads prefix is optional and is not a workspace/component selector.
 name: beadsStoryFlow
 repos:

package/examples/config-reference.yaml

@@ -118,7 +118,11 @@ repos:
 #
 # Beads uses the shared taskConfig fields (filters, assignee, transitionTo,
 # templates) but does not accept Jira-only project/component fields. beadsDir
-# is required at repo scope and must not be supplied only at root scope.
+# is required at repo scope and must not be supplied only at root scope. The
+# registered code path is the bd working directory; beadsDir selects the
+# workspace/database. Shared workspaces isolate parents with the derived
+# reserved repo:<lowercase-repo-name> label (the registered name may be at
+# most 250 ASCII characters), not with workflow labels.
 #
 # Pi variant:
 # harnessPlugin: pi

package/internal/execution/goworkflows/activities.go

@@ -44,6 +44,21 @@ func (a *Activities) runSpec(w run.Work) runner.RunSpec {
 	}
 }
 
+// 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
+}
+
 // EnsureMailboxes ensures one mailbox per work node and returns the
 // node-to-mailbox map.
 func (a *Activities) EnsureMailboxes(ctx context.Context, w run.Work, specs []task.MailboxSpec) (map[string]task.Mailbox, error) {
@@ -220,6 +235,10 @@ func (a *Activities) EnsureNodeRuntime(ctx context.Context, nw run.NodeWork, rep
 	if err != nil {
 		return err
 	}
+	spec.TaskEnv, err = a.agentEnv(nw.Repo)
+	if err != nil {
+		return err
+	}
 	cmd, err := a.Harness.BuildCommand(spec)
 	if err != nil {
 		return err

package/internal/execution/goworkflows/engine_test.go

@@ -71,7 +71,7 @@ func TestMailboxDescriptionAndLaunchPromptAreTaskSystemNeutral(t *testing.T) {
 		if err != nil {
 			t.Fatal(err)
 		}
-		want := "Task system: " + taskSystem + "\nUse the " + taskSystem + " 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\nReturn the complete report directly. Relay-flow will show a native TUI approval dialog after the report is valid. Do not use OpenCode's Question tool for relay-flow approval."
+		want := "Task system: " + taskSystem + "\nUse the " + taskSystem + " 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\nReturn the complete report directly. Relay-flow will show a native TUI approval dialog after the report is valid. Do not use OpenCode's Question tool for relay-flow approval."
 		if prompt != want {
 			t.Fatalf("RenderPrompt(%s) = %q, want %q", taskSystem, prompt, want)
 		}

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.6-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.6-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

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.5-alpha",
+  "version": "0.2.6-alpha",
   "description": "Graph-based agent workflow engine — tracker-agnostic, pluggable runners",
   "bin": {
     "relay-flow": "./bin/relay-flow.js",