relay-flow 0.2.4-alpha → 0.2.6-alpha

package/internal/harness/pi/pi.go

@@ -1,7 +1,7 @@
 // Package pi is the built-in launch-time Harness adapter for the Pi coding
 // agent. Pi supplies one built-in coding agent, represented by the logical
-// relay-flow agent name "default", plus repository-owned role prompts under
-// .pi/roles. The runtime extension is installed by the user and owns report
+// relay-flow agent name "default", plus project-owned prompt templates under
+// .pi/prompts. The runtime extension is installed by the user and owns report
 // parsing and delivery.
 package pi
 
@@ -24,7 +24,9 @@ const (
 	defaultInitialPrompt = `Task system: {{taskSystem}}
 Use the {{taskSystem}} tools to read the parent ticket {{ticket}}.
 
-Your mailbox is {{mailbox}}. Read its description and comments for node instructions and feedback.`
+Your mailbox is {{mailbox}}. Read its description and comments for node instructions and feedback.
+
+Keep the summary brief, and make the feedback as detailed and actionable as possible for the next agent.`
 	defaultFeedbackPrompt = `New feedback was added to the comments section of your mailbox subtask {{mailbox}}. Read it.`
 )
 
@@ -97,11 +99,11 @@ func New(cfg ...Config) *Harness {
 // in each repository.
 func (*Harness) SetupRepo(context.Context, string) error { return nil }
 
-// ValidateAgent accepts Pi's built-in logical agent or a repository role
-// prompt. Pi has no named-agent listing API, so custom roles are verified by
-// checking for a readable, non-empty .pi/roles/<agent>.md file.
-func (*Harness) ValidateAgent(_ context.Context, repoPath, agent string) error {
-	if _, err := resolveRolePrompt(repoPath, agent); err != nil {
+// ValidateAgent checks the Pi executable and the prompt-template command name.
+// Pi owns prompt-template discovery; relay-flow does not inspect or register
+// the user's project-owned .pi/prompts files.
+func (*Harness) ValidateAgent(_ context.Context, _ string, agent string) error {
+	if err := validateAgentName(agent); err != nil {
 		return err
 	}
 	if _, err := exec.LookPath("pi"); err != nil {
@@ -110,39 +112,33 @@ func (*Harness) ValidateAgent(_ context.Context, repoPath, agent string) error {
 	return nil
 }
 
-func resolveRolePrompt(repoPath, agent string) (string, error) {
+func validateAgentName(agent string) error {
 	if agent == "default" {
-		return "", nil
+		return nil
 	}
 	if strings.TrimSpace(agent) == "" || strings.TrimSpace(agent) != agent || strings.ContainsAny(agent, `/\\`) || agent == "." || agent == ".." {
-		return "", fmt.Errorf("pi: invalid role %q", agent)
-	}
-	if repoPath == "" {
-		return "", fmt.Errorf("pi: role %q requires a repository path", agent)
-	}
-	root, err := filepath.Abs(repoPath)
-	if err != nil {
-		return "", fmt.Errorf("pi: resolve repository path for role %q: %w", agent, err)
-	}
-	path := filepath.Join(root, ".pi", "roles", agent+".md")
-	info, err := os.Stat(path)
-	if err != nil {
-		if os.IsNotExist(err) {
-			return "", fmt.Errorf("pi: role %q is unavailable; expected %s", agent, path)
-		}
-		return "", fmt.Errorf("pi: inspect role %q: %w", agent, err)
+		return fmt.Errorf("pi: invalid prompt template %q", agent)
 	}
-	if !info.Mode().IsRegular() {
-		return "", fmt.Errorf("pi: role %q is not a regular file: %s", agent, path)
+	return nil
+}
+
+func promptTemplatePath(agent string) string {
+	return filepath.Join(".pi", "prompts", agent+".md")
+}
+
+func applyPromptTemplate(agent, prompt string) string {
+	if agent == "" || agent == "default" {
+		return prompt
 	}
-	contents, err := os.ReadFile(path)
-	if err != nil {
-		return "", fmt.Errorf("pi: read role %q: %w", agent, err)
+	prefix := "/" + agent
+	if prompt == prefix || strings.HasPrefix(prompt, prefix+" ") ||
+		strings.HasPrefix(prompt, prefix+"\t") || strings.HasPrefix(prompt, prefix+"\n") {
+		return prompt
 	}
-	if strings.TrimSpace(string(contents)) == "" {
-		return "", fmt.Errorf("pi: role %q is empty: %s", agent, path)
+	if prompt == "" {
+		return prefix
 	}
-	return path, nil
+	return prefix + " " + prompt
 }
 
 // FindSession is intentionally discovery-free. Normal execution resumes only
@@ -152,8 +148,10 @@ func (*Harness) FindSession(context.Context, string, string) (harness.Session, b
 }
 
 // RenderPrompt renders the selected initial or feedback template and the
-// node's nudge template. HITL approval is not encoded in the prompt; the Pi
-// extension asks for approval through ctx.ui.select.
+// node's nudge template. Named Pi agents are native prompt-template commands,
+// so the complete rendered text is supplied as the command arguments. HITL
+// approval is not encoded in the prompt; the Pi extension asks for approval
+// through ctx.ui.select.
 func (h *Harness) RenderPrompt(kind harness.PromptKind, data harness.PromptData, nudgeTemplate string) (string, error) {
 	var tmpl string
 	switch kind {
@@ -164,18 +162,23 @@ func (h *Harness) RenderPrompt(kind harness.PromptKind, data harness.PromptData,
 	default:
 		return "", fmt.Errorf("pi: unknown prompt kind %q", kind)
 	}
-	return appendPrompt(renderTemplate(tmpl, data), renderTemplate(nudgeTemplate, data)), nil
+	if data.Agent != "" {
+		if err := validateAgentName(data.Agent); err != nil {
+			return "", err
+		}
+	}
+	prompt := appendPrompt(renderTemplate(tmpl, data), renderTemplate(nudgeTemplate, data))
+	return applyPromptTemplate(data.Agent, prompt), nil
 }
 
 // BuildCommand returns the interactive Pi invocation. The runner supplies a
 // PTY for Pi's stdin/stdout; the rendered prompt is the final positional argv
-// value. A custom role adds Pi's --append-system-prompt option with the role
-// file from the registered repository. Pi 0.84.1 rejects a bare -- terminator,
-// so none is included. A non-empty ResumeID selects Pi's exact session-id
-// resume option.
+// value. A named workflow agent adds Pi's --prompt-template option for the
+// project-owned .pi/prompts/<agent>.md file and invokes it with its native
+// slash-command syntax. Pi 0.84.1 rejects a bare -- terminator, so none is
+// included. A non-empty ResumeID selects Pi's exact session-id resume option.
 func (*Harness) BuildCommand(spec harness.LaunchSpec) (runner.Command, error) {
-	rolePath, err := resolveRolePrompt(spec.RepoPath, spec.Agent)
-	if err != nil {
+	if err := validateAgentName(spec.Agent); err != nil {
 		return runner.Command{}, err
 	}
 	nextSteps, err := json.Marshal(spec.NextSteps)
@@ -186,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,
@@ -196,15 +205,17 @@ 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 rolePath != "" {
-		args = append(args, "--append-system-prompt", rolePath)
+	if spec.Agent != "default" {
+		args = append(args, "--prompt-template", promptTemplatePath(spec.Agent))
 	}
 	if spec.ResumeID != "" {
 		args = append(args, "--session-id", spec.ResumeID)
 	}
-	args = append(args, spec.Prompt)
+	args = append(args, applyPromptTemplate(spec.Agent, spec.Prompt))
 	return runner.Command{
 		Executable: "pi",
 		Args:       args,

package/internal/harness/pi/pi_test.go

@@ -20,7 +20,7 @@ import (
 // shape. The fake is intentionally an executable on PATH rather than a
 // production lookup seam: Pi availability is covered separately, while this
 // test verifies the opaque runner command and its handoff to the ticket
-// environment, including an optional repository role prompt.
+// environment, including an optional native prompt template.
 func TestBuildCommandUsesStrictPiCLIContract(t *testing.T) {
 	fakeDir, capturePath := strictPiCLI(t)
 	t.Setenv("PATH", fakeDir+string(os.PathListSeparator)+os.Getenv("PATH"))
@@ -123,19 +123,18 @@ func TestBuildCommandKeepsDashPrefixedPromptPositional(t *testing.T) {
 	}
 }
 
-func TestBuildCommandAddsExistingRolePrompt(t *testing.T) {
+func TestBuildCommandUsesNativePromptTemplate(t *testing.T) {
 	fakeDir, capturePath := strictPiCLI(t)
 	t.Setenv("PATH", fakeDir+string(os.PathListSeparator)+os.Getenv("PATH"))
 	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")
 
 	spec := launchSpec(t)
 	spec.Agent = "coder"
-	rolePath := writePiRole(t, spec.RepoPath, spec.Agent, "You are the coder for relay-flow.\n")
 	cmd, err := newPiHarness(t).BuildCommand(spec)
 	if err != nil {
 		t.Fatalf("BuildCommand: %v", err)
 	}
-	want := []string{"--name", spec.Title, "--append-system-prompt", rolePath, spec.Prompt}
+	want := []string{"--name", spec.Title, "--prompt-template", ".pi/prompts/coder.md", "/coder " + spec.Prompt}
 	if !reflect.DeepEqual(cmd.Args, want) {
 		t.Fatalf("Args = %#v, want %#v", cmd.Args, want)
 	}
@@ -143,14 +142,28 @@ func TestBuildCommandAddsExistingRolePrompt(t *testing.T) {
 	if !reflect.DeepEqual(capture.args, want) {
 		t.Fatalf("fake Pi args = %#v, want %#v", capture.args, want)
 	}
+
+	spec.ResumeID = "session-123"
+	cmd, err = newPiHarness(t).BuildCommand(spec)
+	if err != nil {
+		t.Fatalf("BuildCommand(resume): %v", err)
+	}
+	want = []string{"--name", spec.Title, "--prompt-template", ".pi/prompts/coder.md", "--session-id", spec.ResumeID, "/coder " + spec.Prompt}
+	if !reflect.DeepEqual(cmd.Args, want) {
+		t.Fatalf("resume Args = %#v, want %#v", cmd.Args, want)
+	}
 }
 
-func TestBuildCommandRejectsMissingRolePrompt(t *testing.T) {
+func TestBuildCommandDoesNotValidatePromptTemplateFile(t *testing.T) {
 	spec := launchSpec(t)
 	spec.Agent = "reviewer"
-	_, err := newPiHarness(t).BuildCommand(spec)
-	if err == nil || !strings.Contains(err.Error(), ".pi/roles/reviewer.md") {
-		t.Fatalf("missing role error = %v, want role path", err)
+	cmd, err := newPiHarness(t).BuildCommand(spec)
+	if err != nil {
+		t.Fatalf("BuildCommand: %v", err)
+	}
+	want := []string{"--name", spec.Title, "--prompt-template", ".pi/prompts/reviewer.md", "/reviewer " + spec.Prompt}
+	if !reflect.DeepEqual(cmd.Args, want) {
+		t.Fatalf("Args = %#v, want %#v", cmd.Args, want)
 	}
 }
 
@@ -290,9 +303,12 @@ done
 [ "${1:-}" = "--name" ] || exit 2
 [ "$#" -ge 3 ] || exit 2
 shift 2
-if [ "${1:-}" = "--append-system-prompt" ]; then
+if [ "${1:-}" = "--prompt-template" ]; then
   [ "$#" -ge 3 ] || exit 2
-  [ -s "$2" ] || exit 2
+  case "$2" in
+    .pi/prompts/*.md) ;;
+    *) exit 2 ;;
+  esac
   shift 2
 fi
 if [ "${1:-}" = "--session-id" ]; then

package/internal/harness/pi/prompt_test.go

@@ -29,7 +29,7 @@ func TestPiRenderPromptSubstitutesInitialAndFeedbackData(t *testing.T) {
 	if err != nil {
 		t.Fatalf("RenderPrompt(initial): %v", err)
 	}
-	wantInitial := "Task system: jira\nUse the jira tools to read the parent ticket PAY-101.\n\nYour mailbox is PAY-234. Read its description and comments for node instructions and feedback.\n\nnudge jira|PAY-101|basicFlow|payments|implement|review (when: ready)"
+	wantInitial := "Task system: jira\nUse the jira tools to read the parent ticket PAY-101.\n\nYour mailbox is PAY-234. Read its description and comments for node instructions and feedback.\n\nKeep the summary brief, and make the feedback as detailed and actionable as possible for the next agent.\n\nnudge jira|PAY-101|basicFlow|payments|implement|review (when: ready)"
 	if initial != wantInitial {
 		t.Fatalf("initial prompt = %q, want %q", initial, wantInitial)
 	}
@@ -97,6 +97,35 @@ func TestPiPromptRetainsDefaultAgentLabel(t *testing.T) {
 	}
 }
 
+func TestPiRenderPromptUsesNativeTemplateCommandForNamedAgent(t *testing.T) {
+	h := newPiHarness(t)
+	data := harness.PromptData{
+		TaskSystem: "jira",
+		Ticket:     "PAY-101",
+		Node:       "implement",
+		Agent:      "coder",
+		Mailbox:    "PAY-234",
+	}
+
+	initial, err := h.RenderPrompt(harness.PromptInitial, data, "nudge {{node}}")
+	if err != nil {
+		t.Fatalf("RenderPrompt(initial): %v", err)
+	}
+	wantInitial := "/coder Task system: jira\nUse the jira tools to read the parent ticket PAY-101.\n\nYour mailbox is PAY-234. Read its description and comments for node instructions and feedback.\n\nKeep the summary brief, and make the feedback as detailed and actionable as possible for the next agent.\n\nnudge implement"
+	if initial != wantInitial {
+		t.Fatalf("initial prompt = %q, want %q", initial, wantInitial)
+	}
+
+	feedback, err := h.RenderPrompt(harness.PromptFeedback, data, "feedback nudge")
+	if err != nil {
+		t.Fatalf("RenderPrompt(feedback): %v", err)
+	}
+	wantFeedback := "/coder New feedback was added to the comments section of your mailbox subtask PAY-234. Read it.\n\nfeedback nudge"
+	if feedback != wantFeedback {
+		t.Fatalf("feedback prompt = %q, want %q", feedback, wantFeedback)
+	}
+}
+
 func TestPiPromptsDoNotIncludeOpenCodeQuestionInstructions(t *testing.T) {
 	h := newPiHarness(t)
 	data := harness.PromptData{

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/harness/pi/validation_test.go

@@ -33,93 +33,81 @@ func TestPiValidateAgentRejectsUnavailablePi(t *testing.T) {
 	}
 }
 
-func TestPiValidateAgentAcceptsExistingRoleAndPiOnPath(t *testing.T) {
+func TestPiValidateAgentAcceptsNamedPromptTemplateAndPiOnPath(t *testing.T) {
 	fakeDir := strictPiAvailabilityCLI(t)
 	t.Setenv("PATH", fakeDir)
 	repoPath := t.TempDir()
-	rolePath := writePiRole(t, repoPath, "coder", "You are the coder.\n")
 
 	h := newPiHarness(t)
 	if err := h.ValidateAgent(context.Background(), repoPath, "coder"); err != nil {
-		t.Fatalf("existing role %q rejected: %v", rolePath, err)
+		t.Fatalf("prompt template rejected: %v", err)
 	}
 	if calls := readAvailabilityCalls(t, fakeDir); len(calls) != 0 {
-		t.Fatalf("role validation unexpectedly executed Pi: %v", calls)
+		// ValidateAgent only performs executable lookup; it must not execute Pi.
+		t.Fatalf("unexpected Pi execution during prompt-template validation: %v", calls)
 	}
 }
 
-func TestPiValidateAgentRejectsMissingRoleBeforePiLookup(t *testing.T) {
+func TestPiValidateAgentDoesNotInspectPromptTemplateBeforePiLookup(t *testing.T) {
 	fakeDir := strictPiAvailabilityCLI(t)
 	t.Setenv("PATH", fakeDir)
 
 	h := newPiHarness(t)
 	err := h.ValidateAgent(context.Background(), t.TempDir(), "reviewer")
-	if err == nil || !strings.Contains(err.Error(), ".pi/roles/reviewer.md") {
-		t.Fatalf("missing role error = %v, want role path", err)
+	if err != nil {
+		t.Fatalf("missing prompt template rejected: %v", err)
 	}
 	if calls := readAvailabilityCalls(t, fakeDir); len(calls) != 0 {
-		t.Fatalf("missing role invoked Pi lookup: %v", calls)
+		t.Fatalf("prompt-template validation executed Pi: %v", calls)
 	}
 }
 
-func TestPiValidateAgentRejectsUnsafeRolePath(t *testing.T) {
+func TestPiValidateAgentRejectsUnsafePromptTemplateName(t *testing.T) {
 	fakeDir := strictPiAvailabilityCLI(t)
 	t.Setenv("PATH", fakeDir)
 
 	h := newPiHarness(t)
-	for _, role := range []string{"../coder", "subdir/coder", `subdir\\coder`, " ", "."} {
-		if err := h.ValidateAgent(context.Background(), t.TempDir(), role); err == nil {
-			t.Errorf("unsafe role %q accepted", role)
+	for _, name := range []string{"../coder", "subdir/coder", `subdir\\coder`, " ", "."} {
+		if err := h.ValidateAgent(context.Background(), t.TempDir(), name); err == nil {
+			t.Errorf("unsafe prompt template name %q accepted", name)
 		}
 	}
 	if calls := readAvailabilityCalls(t, fakeDir); len(calls) != 0 {
-		t.Fatalf("unsafe roles invoked Pi lookup: %v", calls)
+		t.Fatalf("unsafe prompt template names invoked Pi lookup: %v", calls)
 	}
 }
 
-func TestPiValidateAgentRejectsEmptyAndNonRegularRoleFiles(t *testing.T) {
+func TestPiValidateAgentAcceptsMissingAndNonRegularPromptTemplateFiles(t *testing.T) {
 	fakeDir := strictPiAvailabilityCLI(t)
 	t.Setenv("PATH", fakeDir)
 
-	emptyRepo := t.TempDir()
-	emptyPath := filepath.Join(emptyRepo, ".pi", "roles", "coder.md")
-	if err := os.MkdirAll(filepath.Dir(emptyPath), 0o755); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(emptyPath, nil, 0o644); err != nil {
-		t.Fatal(err)
-	}
-
-	directoryRepo := t.TempDir()
-	directoryPath := filepath.Join(directoryRepo, ".pi", "roles", "reviewer.md")
-	if err := os.MkdirAll(directoryPath, 0o755); err != nil {
-		t.Fatal(err)
-	}
-
 	h := newPiHarness(t)
-	if err := h.ValidateAgent(context.Background(), emptyRepo, "coder"); err == nil || !strings.Contains(err.Error(), "empty") {
-		t.Fatalf("empty role error = %v, want empty-role error", err)
+	if err := h.ValidateAgent(context.Background(), t.TempDir(), "coder"); err != nil {
+		t.Fatalf("missing prompt template error = %v", err)
 	}
-	if err := h.ValidateAgent(context.Background(), directoryRepo, "reviewer"); err == nil || !strings.Contains(err.Error(), "regular file") {
-		t.Fatalf("directory role error = %v, want non-regular-role error", err)
+	if err := h.ValidateAgent(context.Background(), t.TempDir(), "reviewer"); err != nil {
+		t.Fatalf("non-regular prompt template error = %v", err)
 	}
 	if calls := readAvailabilityCalls(t, fakeDir); len(calls) != 0 {
-		t.Fatalf("invalid role files invoked Pi lookup: %v", calls)
+		t.Fatalf("prompt-template validation executed Pi: %v", calls)
 	}
 }
 
-func TestPiValidateAgentRejectsUnsupportedLabelsWithoutAgentDiscovery(t *testing.T) {
+func TestPiValidateAgentAcceptsAnySafePromptTemplateNameWithoutAgentDiscovery(t *testing.T) {
 	fakeDir := strictPiAvailabilityCLI(t)
 	t.Setenv("PATH", fakeDir)
 
 	h := newPiHarness(t)
-	for _, label := range []string{"build", "plan", "gpt-4o", ""} {
-		if err := h.ValidateAgent(context.Background(), "/srv/payments", label); err == nil {
-			t.Errorf("unsupported agent label %q accepted", label)
+	for _, name := range []string{"build", "plan", "gpt-4o"} {
+		if err := h.ValidateAgent(context.Background(), "/srv/payments", name); err != nil {
+			t.Errorf("safe prompt template name %q rejected: %v", name, err)
 		}
 	}
+	if err := h.ValidateAgent(context.Background(), "/srv/payments", ""); err == nil {
+		t.Error("empty prompt template name accepted")
+	}
 	if calls := readAvailabilityCalls(t, fakeDir); len(calls) != 0 {
-		t.Fatalf("unsupported labels invoked pi instead of rejecting directly: %v", calls)
+		t.Fatalf("prompt-template validation executed Pi: %v", calls)
 	}
 }
 
@@ -154,15 +142,3 @@ func readAvailabilityCalls(t *testing.T, directory string) []string {
 	}
 	return strings.Split(strings.TrimSuffix(string(data), "\x00"), "\x00")
 }
-
-func writePiRole(t *testing.T, repoPath, name, content string) string {
-	t.Helper()
-	path := filepath.Join(repoPath, ".pi", "roles", name+".md")
-	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	return path
-}

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/runner/herdr/herdr.go

@@ -206,6 +206,20 @@ func (a *adapter) ticketWorkspace(ctx context.Context, spec runner.RunSpec) (str
 
 // --- Terminals ---
 
+// DiscoverTerminal finds an existing live pane by its stable title during
+// explicit projection recovery. It never creates a workspace or pane.
+func (a *adapter) DiscoverTerminal(ctx context.Context, spec runner.RunSpec, title string) (runner.Terminal, bool, error) {
+	workspaceID, found, err := a.ticketWorkspace(ctx, spec)
+	if err != nil || !found {
+		return runner.Terminal{}, false, err
+	}
+	handle, _, err := a.recoverTerminal(ctx, workspaceID, title)
+	if err != nil || handle == "" {
+		return runner.Terminal{}, false, err
+	}
+	return a.FindTerminal(ctx, runner.Terminal{ID: handle, Title: title})
+}
+
 // FindTerminal addresses a persisted pane handle directly and returns it only
 // when Herdr still has a live agent process in that pane. A pane restored as a
 // bare shell after a Herdr restart is not a usable agent terminal.

package/internal/runner/herdr/herdr_test.go

@@ -455,6 +455,26 @@ func TestCreateTerminalUsesPublicPaneIDAndStableLabel(t *testing.T) {
 	}
 }
 
+func TestDiscoverTerminalByStableTitle(t *testing.T) {
+	live := &fakeClient{
+		listing: herdrcli.WorktreeListing{Worktrees: []herdrcli.Worktree{{Branch: "PAY-101", OpenWorkspaceID: "w2"}}},
+		tabs:    []herdrcli.Tab{{ID: "tab-1", WorkspaceID: "w2", Label: "PAY-101:coding"}},
+		panes:   []herdrcli.Pane{{ID: "p2", TerminalID: "term-2", WorkspaceID: "w2", TabID: "tab-1", Label: "PAY-101:coding"}},
+		pane:    herdrcli.Pane{ID: "p2", TerminalID: "term-2", WorkspaceID: "w2", TabID: "tab-1", Label: "PAY-101:coding"},
+		info:    herdrcli.ProcessInfo{PaneID: "p2", ShellPID: uint32Pointer(1), ForegroundProcesses: []herdrcli.ForegroundProcess{{PID: 42, Name: "opencode"}}},
+	}
+	discoverer := runner.Runner(newAdapter(live))
+	got, found, err := discoverer.(runner.TerminalDiscoverer).DiscoverTerminal(context.Background(), runner.RunSpec{
+		RepoName: "payments", RepoPath: repoPath, TicketKey: "PAY-101",
+	}, "PAY-101:coding")
+	if err != nil || !found || got.ID != "p2" || got.Title != "PAY-101:coding" {
+		t.Fatalf("DiscoverTerminal = %+v, %v, %v", got, found, err)
+	}
+	if len(live.tabCreateCalls) != 0 || len(live.createCalls) != 0 {
+		t.Fatalf("terminal discovery created runner resources: tabs=%v worktrees=%v", live.tabCreateCalls, live.createCalls)
+	}
+}
+
 func TestFindTerminalAcceptsLiveAgentAndRejectsRestoredShell(t *testing.T) {
 	live := &fakeClient{
 		pane: herdrcli.Pane{ID: "w2:p2", TerminalID: "term_1", WorkspaceID: "w2", Label: "PAY-101:coding"},

package/internal/runner/orca/orca.go

@@ -206,6 +206,39 @@ func (a *adapter) CloseTerminal(ctx context.Context, terminal runner.Terminal) e
 	return err
 }
 
+// DiscoverTerminal finds a live terminal by stable title during explicit
+// projection recovery. It never creates an environment or terminal.
+func (a *adapter) DiscoverTerminal(ctx context.Context, spec runner.RunSpec, title string) (runner.Terminal, bool, error) {
+	repoID, err := a.repoID(ctx, spec.RepoName, spec.RepoPath)
+	if err != nil {
+		return runner.Terminal{}, false, err
+	}
+	worktrees, err := a.cli.ListWorktrees(ctx)
+	if err != nil {
+		return runner.Terminal{}, false, err
+	}
+	var worktreeID string
+	for _, worktree := range worktrees {
+		if worktree.RepoID == repoID && worktree.DisplayName == spec.TicketKey {
+			worktreeID = worktree.ID
+			break
+		}
+	}
+	if worktreeID == "" {
+		return runner.Terminal{}, false, nil
+	}
+	terminals, err := a.cli.ListTerminals(ctx, "id:"+worktreeID)
+	if err != nil {
+		return runner.Terminal{}, false, err
+	}
+	for _, terminal := range terminals {
+		if terminal.Title == title && terminal.Connected {
+			return runner.Terminal{ID: terminal.Handle, Title: title}, true, nil
+		}
+	}
+	return runner.Terminal{}, false, nil
+}
+
 // FindTerminal addresses a persisted handle directly. Normal execution never
 // lists terminals or rediscovers by title.
 func (a *adapter) FindTerminal(ctx context.Context, terminal runner.Terminal) (runner.Terminal, bool, error) {