relay-flow 0.2.4-alpha → 0.2.5-alpha

package/internal/execution/temporal/visibility_lag_test.go

@@ -0,0 +1,415 @@
+package temporal
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/execution/projection"
+	"github.com/rajpopat27/relay-flow/internal/harness"
+	"github.com/rajpopat27/relay-flow/internal/identity"
+	"github.com/rajpopat27/relay-flow/internal/repo"
+	"github.com/rajpopat27/relay-flow/internal/retry"
+	"github.com/rajpopat27/relay-flow/internal/run"
+	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/task"
+	domainworkflow "github.com/rajpopat27/relay-flow/internal/workflow"
+	enumspb "go.temporal.io/api/enums/v1"
+	"go.temporal.io/sdk/client"
+)
+
+func TestTemporalRecoveryReconcilesActiveVisibilityLag(t *testing.T) {
+	if os.Getenv("RELAY_FLOW_TEMPORAL_LIVE") != "1" {
+		t.Skip("set RELAY_FLOW_TEMPORAL_LIVE=1 to run active Visibility-lag recovery against the local server")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+	namespace := "relay-flow-visibility-lag-" + string(identity.NewNodeVisitID())[:12]
+	if err := ensureSpikeNamespace(ctx, "localhost:7233", namespace); err != nil {
+		t.Fatal(err)
+	}
+	root := t.TempDir()
+	database := filepath.Join(root, "state.db")
+	if err := projection.InitDatabaseWithIdentity(database, projection.ExecutorIdentity{
+		ExecutorPlugin: "temporal", TemporalAddress: "localhost:7233", TemporalNamespace: namespace,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	sys := &lagTaskSystem{}
+	rnr := &lagRunner{}
+	hrn := &lagHarness{}
+	registry := repo.NewRegistry()
+	workflow := lagWorkflow()
+	registry.Replace(&repo.Repo{
+		Name: "repo", Path: "/repo", TaskSystem: sys,
+		Workflows: []repo.WorkflowBinding{{Workflow: &workflow}},
+	})
+	engine, err := New(database, Dependencies{
+		Repos: registry, Runner: rnr, Harness: hrn, TaskSystem: "lag-task",
+		TemporalAddress: "localhost:7233", TemporalNamespace: namespace,
+		Runtime: &run.RuntimePolicy{KeepTerminalsAlive: true, KeepSessionsAlive: true},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := engine.Start(ctx); err != nil {
+		t.Fatal(err)
+	}
+	defer engine.Shutdown(context.Background())
+	start := run.Start{
+		ID: identity.NewRunID("repo", workflow.Name, "LAG-1"), Repo: "repo", RepoPath: "/repo",
+		Workflow: workflow, Ticket: task.TicketRef{ID: "LAG-1", Key: "LAG-1", Title: "Visibility lag"},
+		Runtime: run.RuntimePolicy{KeepTerminalsAlive: true, KeepSessionsAlive: true},
+	}
+	created, err := engine.EnsureRun(ctx, start)
+	if err != nil || !created {
+		t.Fatalf("EnsureRun = %v, %v", created, err)
+	}
+	waitForLagState(t, ctx, engine, start.ID, run.StateWaiting)
+	rnr.setLive(true)
+	description, err := engine.client.DescribeWorkflowExecution(ctx, string(start.ID), "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if description.WorkflowExecutionInfo == nil || description.WorkflowExecutionInfo.Execution == nil {
+		t.Fatal("Temporal describe returned no active execution")
+	}
+	runID := description.WorkflowExecutionInfo.Execution.RunId
+	beforeReconcile := countTemporalSignals(t, engine, start.ID, runID, reconcileSignalName)
+	created, err = engine.EnsureRun(ctx, start)
+	if err != nil || created {
+		t.Fatalf("duplicate EnsureRun = %v, %v", created, err)
+	}
+	if got := countTemporalSignals(t, engine, start.ID, runID, reconcileSignalName); got != beforeReconcile {
+		t.Fatalf("healthy terminal reconciliation emitted %d signals, want %d", got, beforeReconcile)
+	}
+	rnr.setLive(false)
+	created, err = engine.EnsureRun(ctx, start)
+	if err != nil || created {
+		t.Fatalf("missing-terminal EnsureRun = %v, %v", created, err)
+	}
+	deadline := time.Now().Add(10 * time.Second)
+	for countTemporalSignals(t, engine, start.ID, runID, reconcileSignalName) <= beforeReconcile {
+		if time.Now().After(deadline) {
+			t.Fatal("missing terminal reconciliation did not persist a reconcile signal")
+		}
+		time.Sleep(100 * time.Millisecond)
+	}
+	description, err = engine.client.DescribeWorkflowExecution(ctx, string(start.ID), "")
+	if err != nil || description.WorkflowExecutionInfo == nil || description.WorkflowExecutionInfo.Execution == nil || description.WorkflowExecutionInfo.Execution.RunId != runID {
+		t.Fatalf("duplicate EnsureRun changed execution: %#v, %v", description.WorkflowExecutionInfo, err)
+	}
+	workflowSnapshot, err := engine.workflowFromHistory(ctx, start.ID, runID)
+	if err != nil || workflowSnapshot.Name != workflow.Name || workflowSnapshot.Nodes["work"].Description != "work" {
+		t.Fatalf("Temporal workflow snapshot = %#v, %v", workflowSnapshot, err)
+	}
+	reportState, err := engine.queryReportState(ctx, start.ID, "not-yet-processed")
+	if err != nil || reportState.State != run.StateWaiting || reportState.CurrentNode != "work" || reportState.CurrentNodeVisitID == "" || reportState.Processed {
+		t.Fatalf("Temporal report-state snapshot = %#v, %v", reportState, err)
+	}
+	if _, err := engine.runs.DB.ExecContext(ctx, `DELETE FROM relay_runs WHERE id = ?`, string(start.ID)); err != nil {
+		t.Fatal(err)
+	}
+	created, err = engine.EnsureRun(ctx, start)
+	if err != nil || created {
+		t.Fatalf("EnsureRun after projection loss = %v, %v", created, err)
+	}
+	if got, err := engine.runs.Get(ctx, start.ID); err != nil || got.CurrentNode != "work" || got.CurrentNodeVisitID == "" {
+		t.Fatalf("reconciled missing projection = %+v, %v", got, err)
+	}
+
+	// A false visible entry models Visibility exposing only an older closed
+	// history for this Workflow ID. Recovery must still use exact DescribeWorkflowExecution
+	// and restore the currently running execution, never start a replacement.
+	if err := engine.reconcileClaimedParents(ctx, map[string]bool{string(start.ID): false}); err != nil {
+		t.Fatalf("reconcile visibility lag: %v", err)
+	}
+	got, err := engine.runs.Get(ctx, start.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.ID != start.ID || got.CurrentNode != "work" || got.State != run.StateWaiting || got.CurrentNodeVisitID == "" {
+		t.Fatalf("reconciled projection = %+v", got)
+	}
+	description, err = engine.client.DescribeWorkflowExecution(ctx, string(start.ID), "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if description.WorkflowExecutionInfo == nil || description.WorkflowExecutionInfo.Execution == nil || description.WorkflowExecutionInfo.Execution.RunId != runID {
+		t.Fatalf("visibility-lag reconciliation changed execution: %#v", description.WorkflowExecutionInfo)
+	}
+	if got := sys.pollCountValue(); got != 1 {
+		t.Fatalf("task-system Poll calls = %d, want one read-only reconciliation poll", got)
+	}
+}
+
+func TestTemporalRecoveryReconcilesClosedHistoryToCurrentExecution(t *testing.T) {
+	if os.Getenv("RELAY_FLOW_TEMPORAL_LIVE") != "1" {
+		t.Skip("set RELAY_FLOW_TEMPORAL_LIVE=1 to run closed-history Visibility lag coverage")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+	namespace := "relay-flow-closed-lag-" + string(identity.NewNodeVisitID())[:12]
+	if err := ensureSpikeNamespace(ctx, "localhost:7233", namespace); err != nil {
+		t.Fatal(err)
+	}
+	path := filepath.Join(t.TempDir(), "state.db")
+	if err := projection.InitDatabaseWithIdentity(path, projection.ExecutorIdentity{ExecutorPlugin: "temporal", TemporalAddress: "localhost:7233", TemporalNamespace: namespace}); err != nil {
+		t.Fatal(err)
+	}
+	sys := &lagTaskSystem{}
+	registry := repo.NewRegistry()
+	wf := lagWorkflow()
+	registry.Replace(&repo.Repo{Name: "repo", Path: "/repo", TaskSystem: sys, Workflows: []repo.WorkflowBinding{{Workflow: &wf}}})
+	engine, err := New(path, Dependencies{Repos: registry, Runner: &lagRunner{}, Harness: &lagHarness{}, TaskSystem: "lag-task", TemporalAddress: "localhost:7233", TemporalNamespace: namespace})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := engine.Start(ctx); err != nil {
+		t.Fatal(err)
+	}
+	defer engine.Shutdown(context.Background())
+	start := run.Start{ID: identity.NewRunID("repo", wf.Name, "LAG-1"), Repo: "repo", RepoPath: "/repo", Workflow: wf, Ticket: task.TicketRef{ID: "LAG-1", Key: "LAG-1", Title: "Closed history lag"}}
+	badWorkflow := wf
+	badWorkflow.Nodes = make(map[string]domainworkflow.Node, len(wf.Nodes))
+	for name, node := range wf.Nodes {
+		badWorkflow.Nodes[name] = node
+	}
+	badWorkflow.Nodes["start"] = domainworkflow.Node{}
+	badStart := start
+	badStart.Workflow = badWorkflow
+	failed, err := engine.client.ExecuteWorkflow(ctx, client.StartWorkflowOptions{ID: string(start.ID), TaskQueue: TaskQueue, WorkflowIDReusePolicy: enumspb.WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY}, TicketWorkflow, badStart)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := failed.Get(ctx, nil); err == nil {
+		t.Fatal("malformed first execution unexpectedly succeeded")
+	}
+	current, err := engine.client.ExecuteWorkflow(ctx, client.StartWorkflowOptions{ID: string(start.ID), TaskQueue: TaskQueue, WorkflowIDReusePolicy: enumspb.WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY}, TicketWorkflow, start)
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitForLagState(t, ctx, engine, start.ID, run.StateWaiting)
+	if err := engine.reconcileClaimedParents(ctx, map[string]bool{string(start.ID): false}); err != nil {
+		t.Fatalf("reconcile closed-history lag: %v", err)
+	}
+	got, err := engine.runs.Get(ctx, start.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.State != run.StateWaiting || got.CurrentNode != "work" || got.CurrentNodeVisitID == "" {
+		t.Fatalf("reconciled current execution projection = %+v", got)
+	}
+	description, err := engine.client.DescribeWorkflowExecution(ctx, string(start.ID), "")
+	if err != nil || description.WorkflowExecutionInfo == nil || description.WorkflowExecutionInfo.Execution == nil || description.WorkflowExecutionInfo.Execution.RunId != current.GetRunID() {
+		t.Fatalf("reconciliation changed current execution: %#v, %v", description.WorkflowExecutionInfo, err)
+	}
+}
+
+func TestTemporalConflictRetryBlocksThenResumes(t *testing.T) {
+	if os.Getenv("RELAY_FLOW_TEMPORAL_LIVE") != "1" {
+		t.Skip("set RELAY_FLOW_TEMPORAL_LIVE=1 to run Temporal conflict retry against the local server")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+	namespace := "relay-flow-conflict-" + string(identity.NewNodeVisitID())[:12]
+	if err := ensureSpikeNamespace(ctx, "localhost:7233", namespace); err != nil {
+		t.Fatal(err)
+	}
+	path := filepath.Join(t.TempDir(), "state.db")
+	if err := projection.InitDatabaseWithIdentity(path, projection.ExecutorIdentity{ExecutorPlugin: "temporal", TemporalAddress: "localhost:7233", TemporalNamespace: namespace}); err != nil {
+		t.Fatal(err)
+	}
+	sys := &lagTaskSystem{applyFailures: 1}
+	registry := repo.NewRegistry()
+	wf := lagWorkflow()
+	registry.Replace(&repo.Repo{Name: "repo", Path: "/repo", TaskSystem: sys, Workflows: []repo.WorkflowBinding{{Workflow: &wf}}})
+	engine, err := New(path, Dependencies{Repos: registry, Runner: &lagRunner{}, Harness: &lagHarness{}, TaskSystem: "lag-task", TemporalAddress: "localhost:7233", TemporalNamespace: namespace})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := engine.Start(ctx); err != nil {
+		t.Fatal(err)
+	}
+	defer engine.Shutdown(context.Background())
+	start := run.Start{ID: identity.NewRunID("repo", wf.Name, "CONFLICT-1"), Repo: "repo", RepoPath: "/repo", Workflow: wf, Ticket: task.TicketRef{ID: "CONFLICT-1", Key: "CONFLICT-1", Title: "Conflict"}}
+	if created, err := engine.EnsureRun(ctx, start); err != nil || !created {
+		t.Fatalf("EnsureRun = %v, %v", created, err)
+	}
+	deadline := time.Now().Add(20 * time.Second)
+	for {
+		got, err := engine.runs.Get(ctx, start.ID)
+		if err == nil && got.State == run.StateBlocked {
+			snapshot, queryErr := engine.queryRunState(ctx, start.ID, "")
+			if queryErr == nil && snapshot.Run.Retry != nil && snapshot.Run.State == run.StateBlocked {
+				break
+			}
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("run never became blocked with retry metadata: %+v, %v", got, err)
+		}
+		time.Sleep(100 * time.Millisecond)
+	}
+	waitForLagState(t, ctx, engine, start.ID, run.StateWaiting)
+	got, err := engine.runs.Get(ctx, start.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.Retry != nil {
+		t.Fatalf("retry metadata remained after conflict recovery: %+v", got.Retry)
+	}
+}
+
+func lagWorkflow() domainworkflow.Workflow {
+	return domainworkflow.Workflow{
+		Name: "lagFlow", Repos: []string{"repo"},
+		Nodes: map[string]domainworkflow.Node{
+			"start": {OnSuccess: []domainworkflow.Route{{Target: "work"}}},
+			"work": {
+				Type: domainworkflow.NodeAgent, Agent: "agent", Description: "work",
+				OnSuccess: []domainworkflow.Route{{Target: "end"}},
+				OnFailure: []domainworkflow.Route{{Target: "end"}},
+			},
+			"end": {},
+		},
+	}
+}
+
+func countTemporalSignals(t *testing.T, engine *Engine, id run.ID, temporalRunID, signalName string) int {
+	t.Helper()
+	iterator := engine.client.GetWorkflowHistory(context.Background(), string(id), temporalRunID, false, enumspb.HISTORY_EVENT_FILTER_TYPE_ALL_EVENT)
+	count := 0
+	for iterator.HasNext() {
+		event, err := iterator.Next()
+		if err != nil {
+			t.Fatalf("read Temporal history for signal count: %v", err)
+		}
+		if event.GetEventType() == enumspb.EVENT_TYPE_WORKFLOW_EXECUTION_SIGNALED && event.GetWorkflowExecutionSignaledEventAttributes().GetSignalName() == signalName {
+			count++
+		}
+	}
+	return count
+}
+
+func waitForLagState(t *testing.T, ctx context.Context, engine *Engine, id run.ID, state run.State) {
+	t.Helper()
+	for {
+		snapshot, err := engine.queryRunState(ctx, id, "")
+		if err == nil && snapshot.Run.State == state && snapshot.Run.CurrentNode != "" {
+			return
+		}
+		select {
+		case <-ctx.Done():
+			t.Fatalf("waiting for Temporal state %s: %v", state, ctx.Err())
+		case <-time.After(100 * time.Millisecond):
+		}
+	}
+}
+
+type lagTaskSystem struct {
+	mu            sync.Mutex
+	polls         int
+	applyFailures int
+}
+
+var _ task.System = (*lagTaskSystem)(nil)
+
+func (s *lagTaskSystem) Poll(context.Context) ([]task.Ticket, error) {
+	s.mu.Lock()
+	s.polls++
+	s.mu.Unlock()
+	return []task.Ticket{{ID: "LAG-1", Key: "LAG-1", Title: "Visibility lag", WorkflowClaims: []string{"wf:lagFlow"}}}, nil
+}
+func (*lagTaskSystem) CompileFilter(config.RawValues) (func(task.Ticket) bool, error) {
+	return func(task.Ticket) bool { return true }, nil
+}
+func (*lagTaskSystem) Claim(context.Context, task.TicketRef, string) error { return nil }
+func (*lagTaskSystem) ValidateConfig(context.Context, config.RawValues, map[string]config.RawValues) error {
+	return nil
+}
+func (*lagTaskSystem) RenderText(task.TextKind, task.TextData) (string, error) { return "", nil }
+func (*lagTaskSystem) EnsureMailboxes(_ context.Context, _ task.TicketRef, _ string, specs []task.MailboxSpec) (map[string]task.Mailbox, error) {
+	out := make(map[string]task.Mailbox, len(specs))
+	for _, spec := range specs {
+		out[spec.Node] = task.Mailbox{ID: "mb-" + spec.Node, Key: spec.Title, Node: spec.Node}
+	}
+	return out, nil
+}
+func (s *lagTaskSystem) ApplyTaskConfig(context.Context, task.Target, config.RawValues) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.applyFailures > 0 {
+		s.applyFailures--
+		return retry.ConflictError(errors.New("task status is not yet compatible"))
+	}
+	return nil
+}
+func (*lagTaskSystem) CompleteMailbox(context.Context, task.Mailbox) error { return nil }
+func (*lagTaskSystem) HasComment(context.Context, task.Target, string) (bool, error) {
+	return false, nil
+}
+func (*lagTaskSystem) Comment(context.Context, task.Target, string, string) error { return nil }
+func (*lagTaskSystem) ResetForRecovery(context.Context, task.TicketRef, []task.Mailbox, config.RawValues) error {
+	return nil
+}
+func (s *lagTaskSystem) pollCountValue() int { s.mu.Lock(); defer s.mu.Unlock(); return s.polls }
+
+type lagRunner struct {
+	mu   sync.Mutex
+	live bool
+}
+
+var _ runner.Runner = (*lagRunner)(nil)
+
+func (*lagRunner) DiscoverRepos(context.Context) ([]runner.RepoCandidate, error) { return nil, nil }
+func (*lagRunner) ValidateRepo(context.Context, string, string) error            { return nil }
+func (*lagRunner) EnsureEnvironment(context.Context, runner.RunSpec) (runner.Environment, error) {
+	return runner.Environment{ID: "env-lag", Path: "/repo"}, nil
+}
+func (*lagRunner) SetEnvironmentStatus(context.Context, runner.Environment, string) error { return nil }
+func (r *lagRunner) setLive(live bool) {
+	r.mu.Lock()
+	r.live = live
+	r.mu.Unlock()
+}
+
+func (r *lagRunner) FindTerminal(_ context.Context, terminal runner.Terminal) (runner.Terminal, bool, error) {
+	r.mu.Lock()
+	live := r.live
+	r.mu.Unlock()
+	if live && terminal.ID != "" {
+		return terminal, true, nil
+	}
+	return runner.Terminal{}, false, nil
+}
+func (*lagRunner) CreateTerminal(_ context.Context, _ runner.Environment, title string, _ runner.Command) (runner.Terminal, error) {
+	return runner.Terminal{ID: "term-" + title, Title: title}, nil
+}
+func (*lagRunner) EnsureTerminal(_ context.Context, _ runner.Environment, _ runner.Terminal, title string, _ runner.Command) (runner.Terminal, error) {
+	return runner.Terminal{ID: "term-" + title, Title: title}, nil
+}
+func (*lagRunner) SendTerminal(context.Context, runner.Terminal, string) error { return nil }
+func (*lagRunner) CloseTerminal(context.Context, runner.Terminal) error        { return nil }
+func (*lagRunner) CloseTerminals(context.Context, runner.RunSpec) error        { return nil }
+func (*lagRunner) CleanupRun(context.Context, runner.RunSpec) error            { return nil }
+
+type lagHarness struct{}
+
+var _ harness.Harness = (*lagHarness)(nil)
+
+func (*lagHarness) SetupRepo(context.Context, string) error { return nil }
+func (*lagHarness) FindSession(context.Context, string, string) (harness.Session, bool, error) {
+	return harness.Session{}, false, nil
+}
+func (*lagHarness) ValidateAgent(context.Context, string, string) error { return nil }
+func (*lagHarness) RenderPrompt(harness.PromptKind, harness.PromptData, string) (string, error) {
+	return "prompt", nil
+}
+func (*lagHarness) BuildCommand(harness.LaunchSpec) (runner.Command, error) {
+	return runner.Command{Executable: "agent"}, nil
+}

package/internal/harness/opencode/opencode.go

@@ -28,7 +28,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.`
 	defaultHITLPrompt     = `Return 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.`
 )

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

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)
@@ -198,13 +201,13 @@ func (*Harness) BuildCommand(spec harness.LaunchSpec) (runner.Command, error) {
 		"RELAY_FLOW_NEXT_STEPS_JSON": string(nextSteps),
 	}
 	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,