relay-flow 0.2.4-alpha → 0.2.5-alpha

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/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/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) {

package/internal/runner/orca/orca_test.go

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

package/internal/runner/runner.go

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

package/package.json

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