relay-flow 0.2.1-alpha → 0.2.3-alpha

package/internal/execution/goworkflows/mailbox_test.go

@@ -266,6 +266,91 @@ func TestSummaryCurrentFeedbackSelectedNextOnly(t *testing.T) {
 	}
 }
 
+func TestTaskSystemTemplatesRenderMailboxAndSplitOneReport(t *testing.T) {
+	log := newEventLog()
+	sys := newFakeTaskSystem(log)
+	seen := map[task.TextKind][]task.TextData{}
+	sys.renderText = func(kind task.TextKind, data task.TextData) (string, error) {
+		seen[kind] = append(seen[kind], data)
+		switch kind {
+		case task.TextMailboxDescription:
+			return "custom mailbox " + data.Node + " work=" + data.NodeDescription, nil
+		case task.TextSummaryComment:
+			return "custom summary node=" + data.Node + " mailbox=" + data.Mailbox + "\n" + data.SummaryReport, nil
+		case task.TextFeedbackComment:
+			return "custom feedback source=" + data.SourceNode + " target=" + data.TargetNode + " mailbox=" + data.Mailbox + "\n" + data.FeedbackReport, nil
+		default:
+			return "", nil
+		}
+	}
+	engine := newEngine(t, goworkflows.Dependencies{
+		Repos: repoRegistryWith("payments", sys), Runner: newFakeRunner(log), Harness: newFakeHarness(log), TaskSystem: "custom-task",
+	})
+	rid, _ := startRun(engine, threeNodeWorkflow())
+	waitFor(t, 10*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), rid)
+		return r.CurrentNode == "exploration"
+	})
+	if got := sys.specs[1].Description; !strings.Contains(got, "custom mailbox exploration work=explore the code") || !strings.Contains(got, "Required report format:") {
+		t.Fatalf("rendered mailbox description = %q", got)
+	}
+	var explorationData task.TextData
+	for _, data := range seen[task.TextMailboxDescription] {
+		if data.Node == "exploration" {
+			explorationData = data
+		}
+	}
+	for name, got := range map[string]string{
+		"runID":  explorationData.RunID,
+		"ticket": explorationData.Ticket, "workflow": explorationData.Workflow,
+		"repo": explorationData.Repo, "node": explorationData.Node,
+		"nodeType": explorationData.NodeType, "agent": explorationData.Agent,
+		"nodeDescription": explorationData.NodeDescription, "mailbox": explorationData.Mailbox,
+	} {
+		if got == "" {
+			t.Fatalf("mailbox template value %s was empty: %+v", name, explorationData)
+		}
+	}
+	for name, got := range map[string]string{"nextSteps": explorationData.NextSteps, "successRoutes": explorationData.SuccessRoutes, "failureRoutes": explorationData.FailureRoutes} {
+		if !strings.Contains(got, "coding") && name != "failureRoutes" {
+			t.Fatalf("mailbox template %s = %q", name, got)
+		}
+		if name == "failureRoutes" && !strings.Contains(got, "exploration") {
+			t.Fatalf("mailbox template failureRoutes = %q", got)
+		}
+	}
+	report := successReport("coding")
+	report.Feedback = workflow.Feedback{ReasonForNextStep: "reviewed", RequiredActions: "implement", RelevantContext: "ctx", ExpectedResult: "done"}
+	if _, err := engine.SubmitReport(context.Background(), reportRequest(rid, "exploration", report)); err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 10*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), rid)
+		return r.CurrentNode == "coding"
+	})
+	summary := sys.commentBodies("PAY-101-exploration")
+	feedback := sys.commentBodies("PAY-101-coding")
+	if len(summary) != 1 || !strings.Contains(summary[0].Body, "custom summary node=exploration mailbox=PAY-101-exploration") || !strings.Contains(summary[0].Body, "COMPLETED:") {
+		t.Fatalf("summary comments = %+v", summary)
+	}
+	if len(feedback) != 1 || !strings.Contains(feedback[0].Body, "source=exploration target=coding mailbox=PAY-101-coding") || !strings.Contains(feedback[0].Body, "REQUIRED ACTIONS:") {
+		t.Fatalf("feedback comments = %+v", feedback)
+	}
+	if len(seen[task.TextSummaryComment]) != 1 || seen[task.TextSummaryComment][0].SummaryReport == "" {
+		t.Fatalf("summary template data = %+v", seen[task.TextSummaryComment])
+	}
+	if len(seen[task.TextFeedbackComment]) != 1 {
+		t.Fatalf("feedback template data = %+v", seen[task.TextFeedbackComment])
+	}
+	feedbackData := seen[task.TextFeedbackComment][0]
+	if feedbackData.SourceNode != "exploration" || feedbackData.TargetNode != "coding" || feedbackData.Mailbox != "PAY-101-coding" || feedbackData.FeedbackReport == "" {
+		t.Fatalf("feedback template data = %+v", feedbackData)
+	}
+	if len(sys.commentBodies("PAY-101-review")) != 0 {
+		t.Fatal("one report sent feedback to an unselected mailbox")
+	}
+}
+
 // 3.28: end/mailbox behavior, manual status not routing, HITL lifecycle.
 
 func TestManualMailboxStatusDoesNotRouteGraph(t *testing.T) {

package/internal/execution/goworkflows/node_runtime_test.go

@@ -5,6 +5,7 @@ import (
 	"database/sql"
 	"errors"
 	"path/filepath"
+	"reflect"
 	"testing"
 	"time"
 
@@ -222,15 +223,18 @@ func TestEnsureNodeRuntimeUsesDirectIDsAndFallsBackFresh(t *testing.T) {
 	if rt.TerminalID == "" || rt.TerminalID == "dead-term" || rt.SessionID != "dead-session" {
 		t.Fatalf("failed direct IDs not replaced atomically: %+v", rt)
 	}
-	if fr.findCalls != 1 || fh.buildCalls != 1 || fr.createCalls != 1 {
+	if fr.findCalls != 2 || fh.buildCalls != 1 || fr.createCalls != 1 {
 		t.Fatalf("stored-ID replacement calls: find=%d build=%d create=%d", fr.findCalls, fh.buildCalls, fr.createCalls)
 	}
-	if len(fr.findIDs) != 1 || fr.findIDs[0] != "dead-term" {
-		t.Fatalf("FindTerminal IDs = %v, want [dead-term]", fr.findIDs)
+	if len(fr.findIDs) != 2 || fr.findIDs[0] != "dead-term" || fr.findIDs[1] != "dead-term" {
+		t.Fatalf("FindTerminal IDs = %v, want [dead-term dead-term]", fr.findIDs)
 	}
 	if len(fh.resumeIDs) != 1 || fh.resumeIDs[0] != "dead-session" {
 		t.Fatalf("BuildCommand ResumeIDs = %v, want [dead-session]", fh.resumeIDs)
 	}
+	if !reflect.DeepEqual(fh.rendered, []harness.PromptKind{harness.PromptInitial}) {
+		t.Fatalf("dead-terminal rendered prompts = %v, want initial", fh.rendered)
+	}
 	for _, prompt := range fh.prompts {
 		if prompt != "work" {
 			t.Fatalf("same-visit relaunch prompt = %q, want standard prompt only", prompt)
@@ -261,7 +265,7 @@ func TestEnsureNodeRuntimeInitialLaunchAppendsCustomInstructions(t *testing.T) {
 	if err := a.EnsureNodeRuntime(ctx, nw, "", spec, NodeRuntime{}); err != nil {
 		t.Fatal(err)
 	}
-	if len(fh.prompts) != 1 || fh.prompts[0] != "standard prompt\n\ncustom instructions" {
+	if len(fh.prompts) != 1 || fh.prompts[0] != "work\n\ncustom instructions" {
 		t.Fatalf("initial prompt = %q", fh.prompts)
 	}
 	if len(fr.statuses) != 1 || fr.statuses[0] != runner.WorkspaceStatusInReview {
@@ -298,7 +302,7 @@ func TestEnsureNodeRuntimeSendFailureClosesLiveTerminal(t *testing.T) {
 	if fr.closeCalls != 1 || fr.closedIDs[0] != "live-old" {
 		t.Fatalf("old live terminal not closed before replacement: %+v", fr.closedIDs)
 	}
-	if len(fr.sentTexts) != 1 || fr.sentTexts[0] != "New feedback was added to the comments section of your mailbox subtask PAY-234. Read it.\n\nRead the latest review feedback." {
+	if len(fr.sentTexts) != 1 || fr.sentTexts[0] != "feedback\n\nRead the latest review feedback." {
 		t.Fatalf("live revisit prompt = %q", fr.sentTexts)
 	}
 	if len(fh.prompts) != 1 || fh.prompts[0] != "work\n\nRead the latest review feedback." {
@@ -311,6 +315,9 @@ func TestEnsureNodeRuntimeSendFailureClosesLiveTerminal(t *testing.T) {
 	if len(fh.resumeIDs) != 1 || fh.resumeIDs[0] != "session-old" {
 		t.Fatalf("replacement ResumeIDs = %v, want [session-old]", fh.resumeIDs)
 	}
+	if !reflect.DeepEqual(fh.rendered, []harness.PromptKind{harness.PromptFeedback, harness.PromptInitial}) {
+		t.Fatalf("rendered prompts = %v, want feedback then replacement initial", fh.rendered)
+	}
 }
 
 func TestEnsureNodeRuntimeSameVisitSendsNothing(t *testing.T) {
@@ -338,6 +345,10 @@ func TestEnsureNodeRuntimeSameVisitSendsNothing(t *testing.T) {
 	if len(fr.sentTexts) != 0 || fr.createCalls != 0 {
 		t.Fatalf("same visit sent=%q creates=%d", fr.sentTexts, fr.createCalls)
 	}
+	fh := a.Harness.(*runtimeTestHarness)
+	if len(fh.rendered) != 0 || fh.buildCalls != 0 {
+		t.Fatalf("same visit rendered=%v buildCalls=%d, want silence", fh.rendered, fh.buildCalls)
+	}
 }
 
 func TestEnsureNodeRuntimeRejectsStaleVisitWithoutLaunch(t *testing.T) {
@@ -487,8 +498,22 @@ type runtimeTestHarness struct {
 	buildCalls int
 	prompts    []string
 	resumeIDs  []string
+	rendered   []harness.PromptKind
+}
+
+func (h *runtimeTestHarness) RenderPrompt(kind harness.PromptKind, _ harness.PromptData, nudge string) (string, error) {
+	h.rendered = append(h.rendered, kind)
+	prompt := "work"
+	if kind == harness.PromptFeedback {
+		prompt = "feedback"
+	}
+	if nudge != "" {
+		prompt += "\n\n" + nudge
+	}
+	return prompt, nil
 }
 
+func (*runtimeTestHarness) SetupRepo(context.Context, string) error             { return nil }
 func (*runtimeTestHarness) ValidateAgent(context.Context, string, string) error { return nil }
 func (*runtimeTestHarness) FindSession(context.Context, string, string) (harness.Session, bool, error) {
 	return harness.Session{}, false, nil

package/internal/execution/goworkflows/projection.go

@@ -34,6 +34,8 @@ type NodeRuntime struct {
 const relayRunsSchema = `
 CREATE TABLE IF NOT EXISTS relay_runs (
     id TEXT PRIMARY KEY,
+    logical_run_id TEXT,
+    attempt_id INTEGER,
     repo TEXT NOT NULL,
     workflow TEXT NOT NULL,
     ticket_id TEXT NOT NULL,
@@ -86,9 +88,11 @@ func (p *RunProjection) migrate() error {
 		return err
 	}
 	for name, definition := range map[string]string{
-		"retry_error":   "TEXT",
-		"retry_attempt": "INTEGER",
-		"next_retry_at": "DATETIME",
+		"logical_run_id": "TEXT",
+		"attempt_id":     "INTEGER",
+		"retry_error":    "TEXT",
+		"retry_attempt":  "INTEGER",
+		"next_retry_at":  "DATETIME",
 	} {
 		var count int
 		if err := p.DB.QueryRow(`SELECT COUNT(1) FROM pragma_table_info('relay_runs') WHERE name = ?`, name).Scan(&count); err != nil {
@@ -100,6 +104,15 @@ func (p *RunProjection) migrate() error {
 			}
 		}
 	}
+	// Rows created before attempt identities were introduced represent the
+	// original attempt. Backfill the stable logical ID and attempt number so
+	// restart allocation remains numeric and never reuses attempt 1.
+	if _, err := p.DB.Exec(`UPDATE relay_runs SET logical_run_id = id WHERE COALESCE(logical_run_id, '') = ''`); err != nil {
+		return err
+	}
+	if _, err := p.DB.Exec(`UPDATE relay_runs SET attempt_id = 1 WHERE attempt_id IS NULL OR attempt_id = 0`); err != nil {
+		return err
+	}
 	return nil
 }
 
@@ -110,11 +123,19 @@ var errNodeRuntimeNotFound = errors.New("node runtime not found")
 func IsNotFound(err error) bool { return errors.Is(err, errRunNotFound) }
 
 func (p *RunProjection) insertStart(ctx context.Context, s run.Start, now time.Time) error {
+	logicalID := s.LogicalID
+	if logicalID == "" {
+		logicalID = s.ID
+	}
+	attemptID := s.AttemptID
+	if attemptID == 0 {
+		attemptID = 1
+	}
 	_, err := p.DB.ExecContext(ctx, `
-		INSERT INTO relay_runs (id, repo, workflow, ticket_id, ticket_key, state, started_at, updated_at)
-		VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+		INSERT INTO relay_runs (id, logical_run_id, attempt_id, repo, workflow, ticket_id, ticket_key, state, started_at, updated_at)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 		ON CONFLICT(id) DO NOTHING`,
-		string(s.ID), s.Repo, s.Workflow.Name, s.Ticket.ID, s.Ticket.Key,
+		string(s.ID), string(logicalID), int64(attemptID), s.Repo, s.Workflow.Name, s.Ticket.ID, s.Ticket.Key,
 		string(run.StateStarting), now, now)
 	return err
 }
@@ -360,7 +381,7 @@ func nullableString(value string) any {
 
 func (p *RunProjection) get(ctx context.Context, id run.ID) (run.Run, error) {
 	row := p.DB.QueryRowContext(ctx, `
-		SELECT id, repo, workflow, ticket_id, ticket_key, state, current_node, current_node_visit_id, last_error,
+		SELECT id, logical_run_id, attempt_id, repo, workflow, ticket_id, ticket_key, state, current_node, current_node_visit_id, last_error,
 			retry_error, retry_attempt, next_retry_at, started_at, updated_at, finished_at
 		FROM relay_runs WHERE id = ?`, string(id))
 	return scanRun(row)
@@ -368,9 +389,17 @@ func (p *RunProjection) get(ctx context.Context, id run.ID) (run.Run, error) {
 
 func (p *RunProjection) findByTicket(ctx context.Context, ticket string) (run.Run, error) {
 	row := p.DB.QueryRowContext(ctx, `
-		SELECT id, repo, workflow, ticket_id, ticket_key, state, current_node, current_node_visit_id, last_error,
+		SELECT id, logical_run_id, attempt_id, repo, workflow, ticket_id, ticket_key, state, current_node, current_node_visit_id, last_error,
 			retry_error, retry_attempt, next_retry_at, started_at, updated_at, finished_at
-		FROM relay_runs WHERE ticket_key = ? ORDER BY started_at DESC LIMIT 1`, ticket)
+		FROM relay_runs WHERE ticket_key = ? ORDER BY started_at DESC, attempt_id DESC LIMIT 1`, ticket)
+	return scanRun(row)
+}
+
+func (p *RunProjection) findByLogicalID(ctx context.Context, logicalID run.ID) (run.Run, error) {
+	row := p.DB.QueryRowContext(ctx, `
+		SELECT id, logical_run_id, attempt_id, repo, workflow, ticket_id, ticket_key, state, current_node, current_node_visit_id, last_error,
+			retry_error, retry_attempt, next_retry_at, started_at, updated_at, finished_at
+		FROM relay_runs WHERE logical_run_id = ? ORDER BY started_at DESC, attempt_id DESC LIMIT 1`, string(logicalID))
 	return scanRun(row)
 }
 
@@ -380,11 +409,13 @@ type rowScanner interface {
 
 func scanRun(row rowScanner) (run.Run, error) {
 	var r run.Run
+	var logicalID sql.NullString
+	var attemptNumber sql.NullInt64
 	var node, visit, lastErr, retryErr sql.NullString
 	var retryAttempt sql.NullInt64
 	var nextRetry, finished sql.NullTime
 	var started, updated time.Time
-	err := row.Scan(&r.ID, &r.Repo, &r.Workflow, &r.Ticket.ID, &r.Ticket.Key, &r.State,
+	err := row.Scan(&r.ID, &logicalID, &attemptNumber, &r.Repo, &r.Workflow, &r.Ticket.ID, &r.Ticket.Key, &r.State,
 		&node, &visit, &lastErr, &retryErr, &retryAttempt, &nextRetry, &started, &updated, &finished)
 	if errors.Is(err, sql.ErrNoRows) {
 		return run.Run{}, errRunNotFound
@@ -392,6 +423,16 @@ func scanRun(row rowScanner) (run.Run, error) {
 	if err != nil {
 		return run.Run{}, err
 	}
+	if logicalID.Valid && logicalID.String != "" {
+		r.LogicalID = run.ID(logicalID.String)
+	} else {
+		r.LogicalID = r.ID
+	}
+	if attemptNumber.Valid && attemptNumber.Int64 > 0 {
+		r.AttemptID = run.AttemptID(attemptNumber.Int64)
+	} else {
+		r.AttemptID = 1
+	}
 	r.CurrentNode = node.String
 	r.CurrentNodeVisitID = run.NodeVisitID(visit.String)
 	r.LastError = lastErr.String
@@ -410,7 +451,7 @@ func scanRun(row rowScanner) (run.Run, error) {
 }
 
 func (p *RunProjection) list(ctx context.Context, f run.Filter) ([]run.Run, error) {
-	q := `SELECT id, repo, workflow, ticket_id, ticket_key, state, current_node, current_node_visit_id, last_error, retry_error, retry_attempt, next_retry_at, started_at, updated_at, finished_at FROM relay_runs WHERE 1=1`
+	q := `SELECT id, logical_run_id, attempt_id, repo, workflow, ticket_id, ticket_key, state, current_node, current_node_visit_id, last_error, retry_error, retry_attempt, next_retry_at, started_at, updated_at, finished_at FROM relay_runs WHERE 1=1`
 	var args []any
 	if f.Repo != "" {
 		q += ` AND repo = ?`

package/internal/execution/goworkflows/recovery_test.go

@@ -5,6 +5,7 @@ import (
 	"database/sql"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 
@@ -219,6 +220,131 @@ func TestCancelRun(t *testing.T) {
 	}
 }
 
+func TestExplicitRestartCreatesFreshAttemptFromStart(t *testing.T) {
+	log := newEventLog()
+	sys := newFakeTaskSystem(log)
+	fr := newFakeRunner(log)
+	fh := newFakeHarness(log)
+	repos := repoRegistryWith("payments", sys)
+	wf := linearWorkflow(false)
+	workflows := &workflow.Registry{}
+	workflows.Replace(&wf)
+	engine := newEngine(t, goworkflows.Dependencies{
+		Repos: repos, Runner: fr, Harness: fh,
+	})
+	oldID, err := startRun(engine, wf)
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 10*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), oldID)
+		return r.CurrentNode == "coding" && r.CurrentNodeVisitID != ""
+	})
+	if err := engine.CancelRun(context.Background(), oldID, "operator requested restart"); err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 30*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), oldID)
+		return r.State == run.StateCanceled
+	})
+
+	manager := &run.RunManager{
+		Executor: engine, Runs: engine, Repos: repos, Workflows: workflows,
+	}
+	fresh, err := manager.RestartByTicket(context.Background(), "PAY-101")
+	if err != nil {
+		t.Fatalf("RestartByTicket failed: %v", err)
+	}
+	if fresh.ID == oldID || fresh.LogicalID != oldID || fresh.AttemptID != 2 {
+		t.Fatalf("fresh attempt = %+v, want logical=%q attempt=2 and a new ID", fresh, oldID)
+	}
+	oldAck, err := engine.SubmitReport(context.Background(), reportRequest(oldID, "coding", successReport("end")))
+	if err != nil || !oldAck.Accepted || !oldAck.Duplicate {
+		t.Fatalf("stale old-attempt report ack=%+v err=%v, want accepted duplicate", oldAck, err)
+	}
+	if got := string(fresh.ID); got != string(oldID)+"~attempt~2" {
+		t.Fatalf("fresh execution ID = %q, want numeric attempt suffix", got)
+	}
+	waitFor(t, 30*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), fresh.ID)
+		return r.CurrentNode == "coding" && r.CurrentNodeVisitID != ""
+	})
+
+	current, err := engine.GetRun(context.Background(), fresh.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	latest, err := engine.FindRunByTicket(context.Background(), "PAY-101")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if latest.ID != fresh.ID || latest.AttemptID != 2 || latest.LogicalID != oldID {
+		t.Fatalf("ticket lookup = %+v, want latest fresh attempt %q", latest, fresh.ID)
+	}
+	if current.State != run.StateWaiting && current.State != run.StateRunning {
+		t.Fatalf("fresh attempt state = %q, want active node state", current.State)
+	}
+	if got := log.count("prepareRestart:PAY-101"); got != 1 {
+		t.Fatalf("restart preparation calls = %d, want 1", got)
+	}
+	if len(fr.envs) != 1 {
+		t.Fatalf("restart created a second ticket environment: %d", len(fr.envs))
+	}
+	if fr.liveTerminals() != 1 {
+		t.Fatalf("restart left %d live terminals, want one fresh node terminal", fr.liveTerminals())
+	}
+}
+
+func TestRestartStatusConflictIsVisibleAndRecovers(t *testing.T) {
+	log := newEventLog()
+	sys := newFakeTaskSystem(log)
+	fr := newFakeRunner(log)
+	repos := repoRegistryWith("payments", sys)
+	wf := linearWorkflow(false)
+	workflows := &workflow.Registry{}
+	workflows.Replace(&wf)
+	engine := newEngine(t, goworkflows.Dependencies{Repos: repos, Runner: fr, Harness: newFakeHarness(log)})
+	oldID, err := startRun(engine, wf)
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 10*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), oldID)
+		return r.CurrentNode == "coding"
+	})
+	if err := engine.CancelRun(context.Background(), oldID, "operator requested restart"); err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 30*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), oldID)
+		return r.State == run.StateCanceled
+	})
+
+	sys.setStartConflict(true)
+	manager := &run.RunManager{Executor: engine, Runs: engine, Repos: repos, Workflows: workflows}
+	fresh, err := manager.RestartByTicket(context.Background(), "PAY-101")
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 30*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), fresh.ID)
+		return r.State == run.StateBlocked
+	})
+	blocked, err := engine.GetRun(context.Background(), fresh.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(blocked.LastError, "Move ticket PAY-101 to an allowed active start status") {
+		t.Fatalf("blocked LastError = %q, want actionable start-status guidance", blocked.LastError)
+	}
+
+	sys.setStartConflict(false)
+	waitFor(t, 60*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), fresh.ID)
+		return r.CurrentNode == "coding" && r.CurrentNodeVisitID != ""
+	})
+}
+
 func TestCancelDuringRunningActivity(t *testing.T) {
 	// Cancellation cannot interrupt an already-running activity; it waits
 	// for it to return, then runs cancellation cleanup.
@@ -444,6 +570,9 @@ func TestConflictMarksBlockedThenRecovers(t *testing.T) {
 	if r.LastError == "" {
 		t.Fatal("blocked run exposes no conflict error in LastError")
 	}
+	if !strings.Contains(r.LastError, "Restore the task-system state required for node coding") {
+		t.Fatalf("blocked LastError = %q, want actionable node-state guidance", r.LastError)
+	}
 	if sys.mailboxStatusOf("PAY-101-coding") == "Done" {
 		t.Fatal("mailbox completed while state was incompatible; no blind overwrite allowed")
 	}
@@ -759,8 +888,8 @@ func recoverTickets(ctx context.Context, engine *goworkflows.Engine, sys *fakeTa
 		return err
 	}
 	rm := &run.RunManager{Executor: engine, Runs: engine}
-	specsFor := func(w *workflow.Workflow, key string) []task.MailboxSpec {
-		return goworkflows.MailboxSpecs(w, key)
+	specsFor := func(system task.System, work run.Work, w *workflow.Workflow) ([]task.MailboxSpec, error) {
+		return goworkflows.RenderMailboxSpecs(system, work, w)
 	}
 	return recoverpkg.FromTaskSystem(ctx, reg, fr, rm, specsFor)
 }

package/internal/execution/goworkflows/report_contract_fixture_test.go

@@ -0,0 +1,31 @@
+package goworkflows
+
+import (
+	"encoding/json"
+	"os"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/run"
+)
+
+func TestSharedReportContractFixtureRendersCommentValues(t *testing.T) {
+	b, err := os.ReadFile("../../../testdata/report-contract.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var fixtures map[string]struct {
+		Envelope       run.ReportRequest `json:"envelope"`
+		SummaryReport  string            `json:"summaryReport"`
+		FeedbackReport string            `json:"feedbackReport"`
+	}
+	if err := json.Unmarshal(b, &fixtures); err != nil {
+		t.Fatal(err)
+	}
+	fixture := fixtures["work"]
+	if got := renderSummaryReport(fixture.Envelope.Report); got != fixture.SummaryReport {
+		t.Fatalf("summaryReport mismatch\ngot:\n%s\nwant:\n%s", got, fixture.SummaryReport)
+	}
+	if got := renderFeedbackReport(fixture.Envelope.Report); got != fixture.FeedbackReport {
+		t.Fatalf("feedbackReport mismatch\ngot:\n%s\nwant:\n%s", got, fixture.FeedbackReport)
+	}
+}

package/internal/harness/contract_test.go

@@ -32,6 +32,8 @@ func newFakeHarness() *fakeHarness {
 	}
 }
 
+func (f *fakeHarness) SetupRepo(context.Context, string) error { return nil }
+
 func (f *fakeHarness) ValidateAgent(_ context.Context, _, agent string) error {
 	if !f.agents[agent] {
 		return errUnknownAgent
@@ -44,6 +46,14 @@ func (f *fakeHarness) FindSession(_ context.Context, _, title string) (harness.S
 	return s, ok, nil
 }
 
+func (f *fakeHarness) RenderPrompt(_ harness.PromptKind, data harness.PromptData, nudge string) (string, error) {
+	prompt := data.TaskSystem + ":" + data.Ticket + ":" + data.Mailbox
+	if nudge != "" {
+		prompt += "\n\n" + nudge
+	}
+	return prompt, nil
+}
+
 func (f *fakeHarness) BuildCommand(spec harness.LaunchSpec) (runner.Command, error) {
 	// The fake mirrors the required env contract; the real opencode harness
 	// builds the executable/args. NEXT_STEPS_JSON carries the legal targets

package/internal/harness/factory.go

@@ -9,8 +9,12 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/config"
 )
 
-// Factory constructs a Harness from root harness config.
-type Factory func(config.RawValues) (Harness, error)
+// Factory constructs a Harness from root harness config and supplies the
+// selected harness's init defaults without coupling core to an adapter.
+type Factory struct {
+	DefaultConfig func() config.RawValues
+	New           func(config.RawValues) (Harness, error)
+}
 
 var (
 	registryMu sync.RWMutex
@@ -35,7 +39,25 @@ func New(name string, cfg config.RawValues) (Harness, error) {
 	if !ok {
 		return nil, fmt.Errorf("harness: unknown plugin %q (registered: %s)", name, strings.Join(Names(), ", "))
 	}
-	return f(cfg)
+	return f.New(config.Merge(defaultConfig(f), cfg))
+}
+
+// Defaults returns a fresh copy of the named harness's root config defaults.
+func Defaults(name string) (config.RawValues, error) {
+	registryMu.RLock()
+	f, ok := registry[name]
+	registryMu.RUnlock()
+	if !ok {
+		return nil, fmt.Errorf("harness: unknown plugin %q (registered: %s)", name, strings.Join(Names(), ", "))
+	}
+	return config.Merge(defaultConfig(f)), nil
+}
+
+func defaultConfig(f Factory) config.RawValues {
+	if f.DefaultConfig == nil {
+		return nil
+	}
+	return f.DefaultConfig()
 }
 
 // ValidateName returns an error listing registered names when name is not

package/internal/harness/harness.go

@@ -1,7 +1,7 @@
-// Package harness defines the harness contract: agent validation, session
-// discovery, resume syntax, and launch command construction. The runner
-// executes the returned command; the harness never manipulates runner
-// state.
+// Package harness defines the harness contract: repository setup, prompt
+// rendering, agent validation, session discovery, resume syntax, and launch
+// command construction. The runner executes the returned command; the harness
+// never manipulates runner state.
 package harness
 
 import (
@@ -17,6 +17,29 @@ type Session struct {
 	Title string
 }
 
+type PromptKind string
+
+const (
+	PromptInitial  PromptKind = "initial"
+	PromptFeedback PromptKind = "feedback"
+)
+
+// PromptData is the task-system-neutral data core supplies to the selected
+// harness. Harness templates, including HITL instructions, are rendered only
+// by the harness.
+type PromptData struct {
+	TaskSystem      string
+	Ticket          string
+	Workflow        string
+	Repo            string
+	Node            string
+	NodeType        workflow.NodeType
+	Agent           string
+	NodeDescription string
+	NextSteps       string
+	Mailbox         string
+}
+
 type LaunchSpec struct {
 	RunID       identity.RunID
 	NodeVisitID identity.NodeVisitID
@@ -30,12 +53,15 @@ type LaunchSpec struct {
 	Title       string
 	Prompt      string
 	NudgePrompt string
+	PromptData  PromptData
 	NextSteps   []workflow.Route
 	ResumeID    string
 }
 
 type Harness interface {
+	SetupRepo(ctx context.Context, repoPath string) error
 	ValidateAgent(ctx context.Context, repoPath, agent string) error
 	FindSession(ctx context.Context, repoPath, title string) (Session, bool, error)
+	RenderPrompt(kind PromptKind, data PromptData, nudgeTemplate string) (string, error)
 	BuildCommand(spec LaunchSpec) (runner.Command, error)
 }