relay-flow 0.2.0-alpha → 0.2.1-alpha

package/cmd/relay-flow/scenario_test.go

@@ -2,9 +2,11 @@ package main
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
+	"fmt"
 	"path/filepath"
-	"sort"
+	"reflect"
 	"strings"
 	"sync"
 	"testing"
@@ -14,18 +16,26 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/execution/goworkflows"
 	"github.com/rajpopat27/relay-flow/internal/harness"
 	"github.com/rajpopat27/relay-flow/internal/identity"
+	"github.com/rajpopat27/relay-flow/internal/paths"
 	"github.com/rajpopat27/relay-flow/internal/repo"
 	runsvc "github.com/rajpopat27/relay-flow/internal/run"
 	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/server"
 	"github.com/rajpopat27/relay-flow/internal/task"
 	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
-const scenarioTaskPlugin = "scenario-e2e-task"
+const (
+	scenarioTaskPlugin    = "scenario-e2e-task"
+	scenarioRunnerPlugin  = "scenario-e2e-runner"
+	scenarioHarnessPlugin = "scenario-e2e-harness"
+)
 
 var (
-	scenarioFactoryMu     sync.Mutex
-	scenarioFactorySystem task.System
+	scenarioFactoryMu      sync.Mutex
+	scenarioFactorySystem  task.System
+	scenarioFactoryRunner  runner.Runner
+	scenarioFactoryHarness harness.Harness
 )
 
 func init() {
@@ -40,9 +50,34 @@ func init() {
 			if scenarioFactorySystem == nil {
 				return nil, errors.New("scenario task system not configured")
 			}
+			if fake, ok := scenarioFactorySystem.(*scenarioTaskSystem); ok {
+				fake.log.add("factory:task:" + scenarioTaskPlugin)
+			}
 			return scenarioFactorySystem, nil
 		},
 	})
+	runner.Register(scenarioRunnerPlugin, func(config.RawValues) (runner.Runner, error) {
+		scenarioFactoryMu.Lock()
+		defer scenarioFactoryMu.Unlock()
+		if scenarioFactoryRunner == nil {
+			return nil, errors.New("scenario runner not configured")
+		}
+		if fake, ok := scenarioFactoryRunner.(*scenarioRunner); ok {
+			fake.log.add("factory:runner:" + scenarioRunnerPlugin)
+		}
+		return scenarioFactoryRunner, nil
+	})
+	harness.Register(scenarioHarnessPlugin, func(config.RawValues) (harness.Harness, error) {
+		scenarioFactoryMu.Lock()
+		defer scenarioFactoryMu.Unlock()
+		if scenarioFactoryHarness == nil {
+			return nil, errors.New("scenario harness not configured")
+		}
+		if fake, ok := scenarioFactoryHarness.(*scenarioHarness); ok {
+			fake.log.add("factory:harness:" + scenarioHarnessPlugin)
+		}
+		return scenarioFactoryHarness, nil
+	})
 }
 
 func setScenarioFactorySystem(system task.System) {
@@ -51,6 +86,14 @@ func setScenarioFactorySystem(system task.System) {
 	scenarioFactoryMu.Unlock()
 }
 
+func setScenarioFactoryAdapters(system task.System, rnr runner.Runner, hrn harness.Harness) {
+	scenarioFactoryMu.Lock()
+	scenarioFactorySystem = system
+	scenarioFactoryRunner = rnr
+	scenarioFactoryHarness = hrn
+	scenarioFactoryMu.Unlock()
+}
+
 // These scenarios exercise the same composition chain as serve:
 // RepoPoller/handleBatch -> RunManager -> real go-workflows SQLite engine.
 // The only replacements are the documented task, runner, and harness seams.
@@ -89,6 +132,130 @@ func TestScenarioHappyPath(t *testing.T) {
 	assertExactHappyEffects(t, f)
 }
 
+func TestCompositionRootSelectsAlternatePluginsForDurableRun(t *testing.T) {
+	log := newScenarioLog()
+	tasks := newScenarioTaskSystem(log)
+	rnr := newScenarioRunner(log)
+	hrn := newScenarioHarness(log)
+	setScenarioFactoryAdapters(tasks, rnr, hrn)
+
+	root := filepath.Join(t.TempDir(), ".relay-flow")
+	t.Setenv("RELAY_FLOW_HOME", root)
+	p, err := home()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := paths.Ensure(p); err != nil {
+		t.Fatal(err)
+	}
+	if err := config.SaveMachine(p.Config, &config.Machine{
+		PollIntervalSeconds: 1,
+		TaskPlugin:          scenarioTaskPlugin,
+		TaskConfig:          config.RawValues{"provider": "alternate"},
+		RunnerPlugin:        scenarioRunnerPlugin,
+		RunnerConfig:        config.RawValues{"transport": "opaque"},
+		HarnessPlugin:       scenarioHarnessPlugin,
+		HarnessConfig:       config.RawValues{"runtime": "alternate"},
+		Repos: map[string]config.Repo{
+			scenarioRepo: {Path: scenarioRepoPath, TaskConfig: config.RawValues{"scope": "test"}},
+		},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if err := (&workflow.Store{Dir: p.Workflows}).Put(scenarioWorkflowName, scenarioWorkflowYAML); err != nil {
+		t.Fatal(err)
+	}
+	if err := goworkflows.InitDatabase(p.Database); err != nil {
+		t.Fatal(err)
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	stopped := false
+	go func() { done <- serveRoot(ctx, p, false) }()
+	t.Cleanup(func() {
+		if stopped {
+			return
+		}
+		cancel()
+		select {
+		case <-done:
+		case <-time.After(10 * time.Second):
+		}
+	})
+
+	client := server.NewClient(p.Socket)
+	waitForServer(t, client)
+	var active runsvc.Run
+	waitScenario(t, 10*time.Second, func() bool {
+		var lookupErr error
+		active, lookupErr = client.GetRunByTicket(context.Background(), scenarioTicket)
+		return lookupErr == nil && active.State == runsvc.StateWaiting && active.CurrentNode == "implement"
+	})
+
+	launch := hrn.launch("implement")
+	wantPrompt := "Task system: " + scenarioTaskPlugin + "\nUse the " + scenarioTaskPlugin + " tools to read the parent ticket " + scenarioTicket + "."
+	if !strings.Contains(launch.Prompt, wantPrompt) {
+		t.Fatalf("selected task system did not reach launch prompt: %q", launch.Prompt)
+	}
+	command := rnr.command(scenarioTicket + ":implement")
+	wantArgs := []string{"opaque", launch.Prompt}
+	if command.Executable != "fake-harness" || !reflect.DeepEqual(command.Args, wantArgs) {
+		t.Fatalf("runner command = %#v, want opaque harness command args %#v", command, wantArgs)
+	}
+	for _, event := range []string{
+		"factory:task:" + scenarioTaskPlugin,
+		"factory:runner:" + scenarioRunnerPlugin,
+		"factory:harness:" + scenarioHarnessPlugin,
+		"task-config-validated",
+		"runner-repo-validated",
+		"harness-agent-validated:implementer",
+		"harness-launched:" + scenarioTicket + ":implement",
+		"terminal-created:" + scenarioTicket + ":implement",
+	} {
+		if log.countPrefix(event) == 0 {
+			t.Fatalf("composition did not call selected interface boundary %q; events=%v", event, log.all())
+		}
+	}
+
+	for i, next := range []string{"verify", "pr-review", "end"} {
+		current, getErr := client.GetRunByTicket(context.Background(), scenarioTicket)
+		if getErr != nil {
+			t.Fatal(getErr)
+		}
+		ack, submitErr := client.SubmitReport(context.Background(), runsvc.ReportRequest{
+			RunID: current.ID, Node: current.CurrentNode,
+			ReportID: "alternate-session:message-" + fmt.Sprint(i+1),
+			Report:   scenarioReport(workflow.OutcomeSuccess, next),
+		})
+		if submitErr != nil || !ack.Accepted {
+			t.Fatalf("submit durable report %s -> %s: ack=%+v err=%v", current.CurrentNode, next, ack, submitErr)
+		}
+		if next != "end" {
+			waitScenario(t, 10*time.Second, func() bool {
+				advanced, advanceErr := client.GetRunByTicket(context.Background(), scenarioTicket)
+				return advanceErr == nil && advanced.State == runsvc.StateWaiting && advanced.CurrentNode == next
+			})
+		}
+	}
+	waitScenario(t, 10*time.Second, func() bool {
+		finished, getErr := client.GetRunByTicket(context.Background(), scenarioTicket)
+		return getErr == nil && finished.State == runsvc.StateCompleted
+	})
+	if err := client.Stop(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("serveRoot: %v", err)
+		}
+	case <-time.After(10 * time.Second):
+		t.Fatal("serveRoot did not stop")
+	}
+	stopped = true
+}
+
 func TestScenarioHITLRejectLoop(t *testing.T) {
 	f := newScenarioFixture(t)
 	f.pollOnce()
@@ -629,6 +796,8 @@ type scenarioTaskSystem struct {
 	completeFailures int
 }
 
+var _ task.System = (*scenarioTaskSystem)(nil)
+
 func newScenarioTaskSystem(log *scenarioLog) *scenarioTaskSystem {
 	return &scenarioTaskSystem{
 		log: log, mailboxes: map[string]task.Mailbox{}, specs: map[string]task.MailboxSpec{},
@@ -660,6 +829,7 @@ func (s *scenarioTaskSystem) Claim(_ context.Context, ref task.TicketRef, workfl
 }
 
 func (s *scenarioTaskSystem) ValidateConfig(context.Context, config.RawValues, map[string]config.RawValues) error {
+	s.log.add("task-config-validated")
 	return nil
 }
 
@@ -827,6 +997,8 @@ type scenarioRunner struct {
 	cleanups     int
 }
 
+var _ runner.Runner = (*scenarioRunner)(nil)
+
 func newScenarioRunner(log *scenarioLog) *scenarioRunner {
 	return &scenarioRunner{
 		log: log, environments: map[string]runner.Environment{}, terminals: map[string]*scenarioTerminal{},
@@ -838,7 +1010,10 @@ func (r *scenarioRunner) DiscoverRepos(context.Context) ([]runner.RepoCandidate,
 	return []runner.RepoCandidate{{Name: scenarioRepo, Path: scenarioRepoPath}}, nil
 }
 
-func (r *scenarioRunner) ValidateRepo(context.Context, string, string) error { return nil }
+func (r *scenarioRunner) ValidateRepo(context.Context, string, string) error {
+	r.log.add("runner-repo-validated")
+	return nil
+}
 
 func (r *scenarioRunner) EnsureEnvironment(_ context.Context, spec runner.RunSpec) (runner.Environment, error) {
 	r.mu.Lock()
@@ -852,16 +1027,12 @@ func (r *scenarioRunner) EnsureEnvironment(_ context.Context, spec runner.RunSpe
 	return env, nil
 }
 
-func (r *scenarioRunner) FindTerminal(_ context.Context, _ runner.Environment, title string) (runner.Terminal, bool, error) {
-	r.mu.Lock()
-	defer r.mu.Unlock()
-	t, ok := r.terminals[title]
-	if !ok || !t.live {
-		return runner.Terminal{}, false, nil
-	}
-	return t.terminal, true, nil
+func (r *scenarioRunner) SetEnvironmentStatus(_ context.Context, _ runner.Environment, status string) error {
+	r.log.add("workspace-status:" + status)
+	return nil
 }
-func (r *scenarioRunner) InspectTerminal(_ context.Context, terminal runner.Terminal) (runner.Terminal, bool, error) {
+
+func (r *scenarioRunner) FindTerminal(_ context.Context, terminal runner.Terminal) (runner.Terminal, bool, error) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
 	for _, current := range r.terminals {
@@ -872,8 +1043,15 @@ func (r *scenarioRunner) InspectTerminal(_ context.Context, terminal runner.Term
 	return runner.Terminal{}, false, nil
 }
 func (r *scenarioRunner) SendTerminal(context.Context, runner.Terminal, string) error { return nil }
-func (r *scenarioRunner) CreateTerminal(ctx context.Context, env runner.Environment, title string, command runner.Command) (runner.Terminal, error) {
-	return r.EnsureTerminal(ctx, env, title, command)
+func (r *scenarioRunner) CreateTerminal(_ context.Context, _ runner.Environment, title string, command runner.Command) (runner.Terminal, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	terminal := runner.Terminal{ID: "terminal-" + title, Title: title}
+	r.terminals[title] = &scenarioTerminal{terminal: terminal, live: true}
+	r.commands[title] = append(r.commands[title], command)
+	r.launches[title]++
+	r.log.add("terminal-created:" + title)
+	return terminal, nil
 }
 
 func (r *scenarioRunner) CloseTerminal(_ context.Context, terminal runner.Terminal) error {
@@ -886,18 +1064,13 @@ func (r *scenarioRunner) CloseTerminal(_ context.Context, terminal runner.Termin
 	return nil
 }
 
-func (r *scenarioRunner) EnsureTerminal(_ context.Context, _ runner.Environment, title string, command runner.Command) (runner.Terminal, error) {
-	r.mu.Lock()
-	defer r.mu.Unlock()
-	if existing, ok := r.terminals[title]; ok && existing.live {
-		return existing.terminal, nil
+func (r *scenarioRunner) EnsureTerminal(ctx context.Context, env runner.Environment, stored runner.Terminal, title string, command runner.Command) (runner.Terminal, error) {
+	if terminal, ok, err := r.FindTerminal(ctx, stored); err != nil {
+		return runner.Terminal{}, err
+	} else if ok {
+		return terminal, nil
 	}
-	terminal := runner.Terminal{ID: "terminal-" + title, Title: title}
-	r.terminals[title] = &scenarioTerminal{terminal: terminal, live: true}
-	r.commands[title] = append(r.commands[title], command)
-	r.launches[title]++
-	r.log.add("terminal-created:" + title)
-	return terminal, nil
+	return r.CreateTerminal(ctx, env, title, command)
 }
 
 func (r *scenarioRunner) CloseTerminals(context.Context, runner.RunSpec) error {
@@ -948,11 +1121,16 @@ type scenarioHarness struct {
 	launches map[string][]harness.LaunchSpec
 }
 
+var _ harness.Harness = (*scenarioHarness)(nil)
+
 func newScenarioHarness(log *scenarioLog) *scenarioHarness {
 	return &scenarioHarness{log: log, sessions: map[string]harness.Session{}, launches: map[string][]harness.LaunchSpec{}}
 }
 
-func (h *scenarioHarness) ValidateAgent(context.Context, string, string) error { return nil }
+func (h *scenarioHarness) ValidateAgent(_ context.Context, _, agent string) error {
+	h.log.add("harness-agent-validated:" + agent)
+	return nil
+}
 
 func (h *scenarioHarness) FindSession(_ context.Context, _ string, title string) (harness.Session, bool, error) {
 	h.mu.Lock()
@@ -969,6 +1147,7 @@ func (h *scenarioHarness) BuildCommand(spec harness.LaunchSpec) (runner.Command,
 	h.log.add("harness-launched:" + spec.Title)
 	return runner.Command{
 		Executable: "fake-harness",
+		Args:       []string{"opaque", spec.Prompt},
 		Env: map[string]string{
 			"RELAY_FLOW_RUN_ID":          string(spec.RunID),
 			"RELAY_FLOW_WORKFLOW":        spec.Workflow,
@@ -993,12 +1172,8 @@ func (h *scenarioHarness) launch(node string) harness.LaunchSpec {
 }
 
 func routesJSON(routes []workflow.Route) string {
-	parts := make([]string, 0, len(routes))
-	for _, route := range routes {
-		parts = append(parts, route.Target)
-	}
-	sort.Strings(parts)
-	return "[\"" + strings.Join(parts, "\",\"") + "\"]"
+	b, _ := json.Marshal(routes)
+	return string(b)
 }
 
 type scenarioRepoLookup struct{ reg *repo.Registry }

package/cmd/relay-flow/serve.go

@@ -204,6 +204,7 @@ func serveRoot(ctx context.Context, p paths.Paths, recover bool) error {
 		Repos:         repoReg,
 		Runner:        rnr,
 		Harness:       hrn,
+		TaskSystem:    cfg.TaskPlugin,
 		RetentionDays: cfg.CompletedRunRetentionDays,
 		Runtime: &runsvc.RuntimePolicy{
 			KeepTerminalsAlive: cfg.KeepTerminalsAlive,

package/examples/default-story-workflow.yaml

@@ -0,0 +1,88 @@
+# Copy this file and replace "payments" with one or more registered repo names.
+# Optional fields are shown commented; uncomment only the behavior you need.
+name: defaultStoryFlow
+repos:
+  - payments
+cleanupRunnerOnEnd: true
+
+taskConfig:
+  filters:
+    parentStatuses:
+      - To Do
+    issueTypes:
+      - Story
+    # labels:
+    #   - coding
+    # assignees:
+    #   - owner@example.com
+  # assignee: default-node-owner@example.com
+  # project: PAY
+  # component: api
+  # transitionTo:
+  #   parentStatus: In Progress
+  #   taskStatus: In Progress
+
+nodes:
+  start:
+    taskConfig:
+      transitionTo:
+        parentStatus: In Progress
+    onSuccess:
+      - target: implement
+        when: The parent story is ready for implementation
+
+  implement:
+    type: agent
+    agent: coding
+    description: Implement the parent story and verify the changes.
+    # nudgePrompt: "Finish {{node}} for {{ticket}} and choose one of: {{nextSteps}}"
+    taskConfig:
+      # assignee: developer@example.com
+      transitionTo:
+        taskStatus: In Progress
+        # parentStatus: In Progress
+    onSuccess:
+      - target: review
+        when: Implementation and verification are complete
+    onFailure:
+      - target: implement
+        when: Implementation needs another pass
+
+  review:
+    type: agent
+    agent: review
+    description: Review the implementation for correctness, regressions, and missing tests.
+    # nudgePrompt: "Complete the review for {{ticket}}. Valid routes: {{nextSteps}}"
+    taskConfig:
+      # assignee: reviewer@example.com
+      transitionTo:
+        taskStatus: In Review
+        # parentStatus: In Review
+    onSuccess:
+      - target: prReview
+        when: The changes are ready for human approval
+    onFailure:
+      - target: implement
+        when: Code changes are required
+
+  prReview:
+    type: hitl
+    agent: review
+    description: Discuss the pull request with the human and obtain approval.
+    # nudgePrompt: "Review {{ticket}} with the human. Valid routes: {{nextSteps}}"
+    taskConfig:
+      # assignee: human-reviewer@example.com
+      transitionTo:
+        taskStatus: In Review
+        # parentStatus: In Review
+    onSuccess:
+      - target: end
+        when: The human approves the review
+    onFailure:
+      - target: implement
+        when: The human requests code changes
+
+  end:
+    taskConfig:
+      transitionTo:
+        parentStatus: Done

package/internal/execution/goworkflows/activities.go

@@ -2,7 +2,6 @@ package goworkflows
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"log/slog"
 	"sort"
@@ -21,10 +20,11 @@ import (
 // Activities holds the replaceable dependencies shared by every durable
 // activity. One Activities value is registered with the activity worker.
 type Activities struct {
-	Repos   *repo.Registry
-	Runner  runner.Runner
-	Harness harness.Harness
-	Runs    *RunProjection
+	Repos      *repo.Registry
+	Runner     runner.Runner
+	Harness    harness.Harness
+	TaskSystem string
+	Runs       *RunProjection
 }
 
 func (a *Activities) taskSystem(repoName string) (task.System, error) {
@@ -97,13 +97,23 @@ func (a *Activities) EnsureEnvironment(ctx context.Context, w run.Work, repoPath
 	return a.Runner.EnsureEnvironment(ctx, spec)
 }
 
+func (a *Activities) SetEnvironmentStatus(ctx context.Context, w run.Work, repoPath, status string) error {
+	spec := a.runSpec(w)
+	spec.RepoPath = repoPath
+	env, err := a.Runner.EnsureEnvironment(ctx, spec)
+	if err != nil {
+		return err
+	}
+	return a.Runner.SetEnvironmentStatus(ctx, env, status)
+}
+
 func (a *Activities) LoadNodeRuntime(ctx context.Context, id run.ID, node string) (NodeRuntime, error) {
 	return a.Runs.loadNodeRuntime(ctx, id, node)
 }
 
 // EnsureNodeRuntime uses only persisted terminal/session IDs on the normal
-// path. A live terminal is rebound to the new visit; otherwise a fresh
-// terminal is created and its direct IDs atomically replace the old binding.
+// path. A live terminal is rebound to the new visit; otherwise EnsureTerminal
+// creates a replacement and its direct ID is persisted immediately.
 func (a *Activities) EnsureNodeRuntime(ctx context.Context, nw run.NodeWork, repoPath string, spec harness.LaunchSpec, rt NodeRuntime) error {
 	a.Runs.runtimeMu.Lock()
 	defer a.Runs.runtimeMu.Unlock()
@@ -124,45 +134,25 @@ func (a *Activities) EnsureNodeRuntime(ctx context.Context, nw run.NodeWork, rep
 	if err != nil {
 		return err
 	}
+	rs := a.runSpec(nw.Work)
+	rs.RepoPath = repoPath
+	env, err := a.Runner.EnsureEnvironment(ctx, rs)
+	if err != nil {
+		return err
+	}
+	status := runner.WorkspaceStatusInProgress
+	if spec.NodeType == workflow.NodeHITL {
+		status = runner.WorkspaceStatusInReview
+	}
+	if err := a.Runner.SetEnvironmentStatus(ctx, env, status); err != nil {
+		return err
+	}
 	hadRuntime := currentRuntime.TerminalID != "" || currentRuntime.SessionID != ""
 	// IDs come from the guarded current row; the activity input's prior visit
 	// is used only to decide whether a live process needs rebinding.
 	rt.TerminalID = currentRuntime.TerminalID
 	rt.SessionID = currentRuntime.SessionID
-	freshSession := false
-	if rt.TerminalID != "" {
-		terminal := runner.Terminal{ID: rt.TerminalID, Title: spec.Title}
-		_, ok, inspectErr := a.Runner.InspectTerminal(ctx, terminal)
-		if inspectErr != nil {
-			return inspectErr
-		}
-		if ok {
-			// Same-visit retry/restart leaves the running turn untouched. A
-			// revisit sends only the new work prompt to the retained session.
-			if !revisit {
-				return a.Runs.replaceNodeRuntime(ctx, nw.RunID, nw.Node, nw.NodeVisitID,
-					rt.TerminalID, rt.SessionID, rt.SessionID)
-			}
-			prompt := followUpPrompt(nw.Mailbox.Key)
-			if spec.NudgePrompt != "" {
-				prompt += "\n\n" + spec.NudgePrompt
-			}
-			if err := a.Runner.SendTerminal(ctx, terminal, prompt); err == nil {
-				return a.Runs.replaceNodeRuntime(ctx, nw.RunID, nw.Node, nw.NodeVisitID,
-					rt.TerminalID, rt.SessionID, rt.SessionID)
-			}
-			// Direct use failed. Close the known live terminal before replacing
-			// it so a second agent process cannot be left running.
-			if err := a.Runner.CloseTerminal(ctx, terminal); err != nil {
-				return err
-			}
-			freshSession = true
-		}
-	}
-
-	if rt.SessionID != "" && !freshSession {
-		spec.ResumeID = rt.SessionID
-	}
+	spec.ResumeID = rt.SessionID
 	// Custom instructions belong to a node entry, not same-visit recovery.
 	if !hadRuntime || revisit {
 		spec.Prompt = appendPrompt(spec.Prompt, spec.NudgePrompt)
@@ -171,34 +161,46 @@ func (a *Activities) EnsureNodeRuntime(ctx context.Context, nw run.NodeWork, rep
 	if err != nil {
 		return err
 	}
-	rs := a.runSpec(nw.Work)
-	rs.RepoPath = repoPath
-	env, err := a.Runner.EnsureEnvironment(ctx, rs)
+	stored := runner.Terminal{ID: rt.TerminalID, Title: spec.Title}
+	terminal, err := a.Runner.EnsureTerminal(ctx, env, stored, spec.Title, cmd)
 	if err != nil {
 		return err
 	}
-	terminal, err := a.Runner.CreateTerminal(ctx, env, spec.Title, cmd)
-	sessionID := rt.SessionID
-	if errors.Is(err, runner.ErrSessionUnavailable) && rt.SessionID != "" {
-		spec.ResumeID = ""
-		cmd, buildErr := a.Harness.BuildCommand(spec)
-		if buildErr != nil {
-			return buildErr
+	// Persist a newly created/replacement handle before any later external
+	// effect. Runtime session registration may update SessionID independently.
+	if err := a.Runs.replaceNodeRuntime(ctx, nw.RunID, nw.Node, nw.NodeVisitID,
+		terminal.ID, rt.SessionID, rt.SessionID); err != nil {
+		// The visit changed after terminal creation. Close the terminal whose
+		// binding was rejected so stale work cannot leak or report.
+		if terminal.ID != rt.TerminalID {
+			_ = a.Runner.CloseTerminal(ctx, terminal)
 		}
-		terminal, err = a.Runner.CreateTerminal(ctx, env, spec.Title, cmd)
-		sessionID = ""
+		return err
+	}
+	if terminal.ID != rt.TerminalID || !revisit {
+		// A newly created terminal receives its prompt in the launch command;
+		// same-visit reuse leaves the running turn untouched.
+		return nil
+	}
+	prompt := followUpPrompt(nw.Mailbox.Key)
+	if spec.NudgePrompt != "" {
+		prompt += "\n\n" + spec.NudgePrompt
 	}
-	if freshSession {
-		sessionID = ""
+	if err := a.Runner.SendTerminal(ctx, terminal, prompt); err == nil {
+		return nil
+	}
+	// Direct use failed. Close the known live terminal before replacing it so
+	// a second agent process cannot be left running.
+	if err := a.Runner.CloseTerminal(ctx, terminal); err != nil {
+		return err
 	}
+	replacement, err := a.Runner.EnsureTerminal(ctx, env, terminal, spec.Title, cmd)
 	if err != nil {
 		return err
 	}
 	if err := a.Runs.replaceNodeRuntime(ctx, nw.RunID, nw.Node, nw.NodeVisitID,
-		terminal.ID, rt.SessionID, sessionID); err != nil {
-		// The visit changed after terminal creation. Close the terminal whose
-		// binding was rejected so stale work cannot leak or report.
-		_ = a.Runner.CloseTerminal(ctx, terminal)
+		replacement.ID, rt.SessionID, rt.SessionID); err != nil {
+		_ = a.Runner.CloseTerminal(ctx, replacement)
 		return err
 	}
 	return nil
@@ -393,15 +395,13 @@ func (a *Activities) ProjectionUpdateRetry(ctx context.Context, id run.ID, statu
 // description, and every legal route with its when explanation.
 func MailboxSpecForNode(wf *workflow.Workflow, ticketKey, name string, n workflow.Node) task.MailboxSpec {
 	var b strings.Builder
-	fmt.Fprintf(&b, "Parent Jira ticket: %s\nNode: %s\nType: %s\nAgent: %s\n\nWork:\n%s\n\nRead this subtask's comments for feedback from previous nodes.",
+	fmt.Fprintf(&b, "Parent ticket: %s\nNode: %s\nType: %s\nAgent: %s\n\nWork:\n%s\n\nRead this subtask's comments for feedback from previous nodes.",
 		ticketKey, name, n.Type, n.Agent, n.Description)
 	if n.Type == workflow.NodeHITL {
 		b.WriteString(`
 
 1. Discuss the task with the human, request the PR link or any missing context, and review the changes. Do not make code changes.
-2. Resolve questions and requested review updates through normal conversation until the human is satisfied with the review.
-3. Present the complete report through OpenCode's Question tool with exactly two options: Approve and Reject.
-4. If approved, output the report verbatim. If rejected, return to step 1.`)
+2. Resolve questions and requested review updates through normal conversation until the human is satisfied with the review.`)
 	}
 	b.WriteString(`
 
@@ -465,8 +465,8 @@ func MailboxSpecs(wf *workflow.Workflow, ticketKey string) []task.MailboxSpec {
 }
 
 // BuildLaunchSpecPrompt points the agent to its parent and isolated mailbox.
-func BuildLaunchSpecPrompt(ticketKey, mailboxKey string) string {
-	return fmt.Sprintf("Read parent Jira ticket %s for the original task context.\n\nYour Jira mailbox subtask is %s. Read only its description and comments for your node instructions and feedback.", ticketKey, mailboxKey)
+func BuildLaunchSpecPrompt(taskSystem, ticketKey, mailboxKey string) string {
+	return fmt.Sprintf("Task system: %s\nUse the %s tools to read the parent ticket %s.\n\nYour mailbox is %s. Read its description and comments for node instructions and feedback.", taskSystem, taskSystem, ticketKey, mailboxKey)
 }
 
 func followUpPrompt(mailboxKey string) string {