relay-flow 0.2.1-alpha → 0.2.2-alpha

package/cmd/relay-flow/scenario_test.go

@@ -41,6 +41,9 @@ var (
 func init() {
 	task.Register(scenarioTaskPlugin, task.Factory{
 		RequiredRepoKeys: func() []string { return nil },
+		DefaultConfig: func() config.RawValues {
+			return config.RawValues{"templates": map[string]any{"format": "alternate"}}
+		},
 		TaskScopeKey: func(config.RawValues, config.RawValues) (string, error) {
 			return "scenario-scope", nil
 		},
@@ -67,16 +70,19 @@ func init() {
 		}
 		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
+	harness.Register(scenarioHarnessPlugin, harness.Factory{
+		DefaultConfig: func() config.RawValues { return config.RawValues{"runtime": "alternate"} },
+		New: 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
+		},
 	})
 }
 
@@ -194,7 +200,7 @@ func TestCompositionRootSelectsAlternatePluginsForDurableRun(t *testing.T) {
 	})
 
 	launch := hrn.launch("implement")
-	wantPrompt := "Task system: " + scenarioTaskPlugin + "\nUse the " + scenarioTaskPlugin + " tools to read the parent ticket " + scenarioTicket + "."
+	wantPrompt := "initial taskSystem=" + scenarioTaskPlugin
 	if !strings.Contains(launch.Prompt, wantPrompt) {
 		t.Fatalf("selected task system did not reach launch prompt: %q", launch.Prompt)
 	}
@@ -416,7 +422,7 @@ func TestScenarioLateRegisterAndLateSubmit(t *testing.T) {
 	}
 	repoService := repo.NewServiceWithRegistry(repo.ServiceConfig{
 		ConfigPath: configPath, TaskPlugin: scenarioTaskPlugin, Runner: fr,
-		Active: engine, Workflows: wfService.Registry(),
+		Harness: fh, Active: engine, Workflows: wfService.Registry(),
 	}, reg)
 	deps := &serveDeps{
 		repos:          repoService,
@@ -785,6 +791,7 @@ type scenarioTaskSystem struct {
 	mu  sync.Mutex
 
 	claimed          bool
+	renderText       func(task.TextKind, task.TextData) (string, error)
 	mailboxes        map[string]task.Mailbox
 	specs            map[string]task.MailboxSpec
 	mailboxStatus    map[string]string
@@ -833,6 +840,22 @@ func (s *scenarioTaskSystem) ValidateConfig(context.Context, config.RawValues, m
 	return nil
 }
 
+func (s *scenarioTaskSystem) RenderText(kind task.TextKind, data task.TextData) (string, error) {
+	if s.renderText != nil {
+		return s.renderText(kind, data)
+	}
+	switch kind {
+	case task.TextMailboxDescription:
+		return "mailbox " + data.Node + ": " + data.NodeDescription, nil
+	case task.TextSummaryComment:
+		return "SUMMARY\n" + data.SummaryReport, nil
+	case task.TextFeedbackComment:
+		return "Feedback from " + data.SourceNode + " to " + data.TargetNode + " mailbox " + data.Mailbox + "\n" + data.FeedbackReport, nil
+	default:
+		return "", fmt.Errorf("unknown task text kind %q", kind)
+	}
+}
+
 func (s *scenarioTaskSystem) EnsureMailboxes(_ context.Context, parent task.TicketRef, _ string, specs []task.MailboxSpec) (map[string]task.Mailbox, error) {
 	s.log.add("mailboxes:ensure")
 	s.mu.Lock()
@@ -1121,6 +1144,8 @@ type scenarioHarness struct {
 	launches map[string][]harness.LaunchSpec
 }
 
+func (*scenarioHarness) SetupRepo(context.Context, string) error { return nil }
+
 var _ harness.Harness = (*scenarioHarness)(nil)
 
 func newScenarioHarness(log *scenarioLog) *scenarioHarness {
@@ -1139,6 +1164,17 @@ func (h *scenarioHarness) FindSession(_ context.Context, _ string, title string)
 	return session, ok, nil
 }
 
+func (h *scenarioHarness) RenderPrompt(kind harness.PromptKind, data harness.PromptData, nudge string) (string, error) {
+	prompt := string(kind) + " taskSystem=" + data.TaskSystem + " mailbox=" + data.Mailbox
+	if data.NodeType == workflow.NodeHITL {
+		prompt += " hitl"
+	}
+	if nudge != "" {
+		prompt += " " + nudge
+	}
+	return prompt, nil
+}
+
 func (h *scenarioHarness) BuildCommand(spec harness.LaunchSpec) (runner.Command, error) {
 	h.mu.Lock()
 	h.launches[spec.Node] = append(h.launches[spec.Node], spec)

package/cmd/relay-flow/serve.go

@@ -35,6 +35,7 @@ import (
 	// Adapter registrations (factories are registered by name via init).
 	_ "github.com/rajpopat27/relay-flow/internal/harness/opencode"
 	_ "github.com/rajpopat27/relay-flow/internal/runner/orca"
+	_ "github.com/rajpopat27/relay-flow/internal/task/beads"
 	_ "github.com/rajpopat27/relay-flow/internal/task/jira"
 )
 
@@ -263,6 +264,7 @@ func serveRoot(ctx context.Context, p paths.Paths, recover bool) error {
 		ConfigPath: p.Config,
 		TaskPlugin: cfg.TaskPlugin,
 		Runner:     rnr,
+		Harness:    hrn,
 		Active:     engine,
 		Workflows:  wfSvc.Registry(),
 	}, repoReg)
@@ -273,8 +275,8 @@ func serveRoot(ctx context.Context, p paths.Paths, recover bool) error {
 	// specs come from the engine so the recover path builds the same
 	// description content as normal run execution.
 	if recover {
-		specsFor := func(wf *workflow.Workflow, ticketKey string) []task.MailboxSpec {
-			return goworkflows.MailboxSpecs(wf, ticketKey)
+		specsFor := func(sys task.System, work runsvc.Work, wf *workflow.Workflow) ([]task.MailboxSpec, error) {
+			return goworkflows.RenderMailboxSpecs(sys, work, wf)
 		}
 		if err := recoverpkg.FromTaskSystem(ctx, repoReg, rnr, runManager, specsFor); err != nil {
 			shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)

package/examples/beads-workflow.yaml

@@ -0,0 +1,74 @@
+# Beads workflow example. Register the code repository with a required
+# repo-scoped taskConfig.beadsDir before submitting this workflow, for example:
+#
+#   relay-flow repo register --name payments --path /work/payments \
+#     --set beadsDir=/work/payments/.beads
+#
+# The Beads prefix is optional and is not a workspace/component selector.
+name: beadsStoryFlow
+repos:
+  - payments
+cleanupRunnerOnEnd: true
+
+taskConfig:
+  filters:
+    # Beads statuses are open, in_progress, blocked, deferred, hooked, closed.
+    parentStatuses:
+      - open
+    issueTypes:
+      - epic
+    labels:
+      - relay-ready
+    # assignees:
+    #   - owner@example.com
+  # Optional shared default; filters.assignees overrides it when provided.
+  # An assignee in effect for a node also assigns that node's mailbox.
+  # assignee: owner@example.com
+
+# transitionTo describes one lifecycle point, so configure it on a node.
+# Omitting it entirely already gives the Jira-equivalent lifecycle:
+# start parent -> in_progress, work mailbox -> in_progress, end parent -> closed.
+# Values are Beads-native, not Jira values such as "In Progress" or "Done".
+nodes:
+  start:
+    taskConfig:
+      transitionTo:
+        parentStatus: in_progress
+    onSuccess:
+      - target: implement
+        when: The Beads parent is ready for implementation
+
+  implement:
+    type: agent
+    agent: build
+    description: Implement the Beads parent and verify the changes.
+    taskConfig:
+      # assignee: developer@example.com
+      transitionTo:
+        taskStatus: in_progress
+    onSuccess:
+      - target: review
+        when: Implementation and verification are complete
+    onFailure:
+      - target: implement
+        when: Implementation needs another pass
+
+  review:
+    type: hitl
+    agent: plan
+    description: Review the implementation and obtain approval.
+    taskConfig:
+      # assignee: reviewer@example.com
+      transitionTo:
+        taskStatus: in_progress
+    onSuccess:
+      - target: end
+        when: The review is approved
+    onFailure:
+      - target: implement
+        when: Changes are requested
+
+  end:
+    taskConfig:
+      transitionTo:
+        parentStatus: closed

package/examples/default-story-workflow.yaml

@@ -2,7 +2,7 @@
 # Optional fields are shown commented; uncomment only the behavior you need.
 name: defaultStoryFlow
 repos:
-  - payments
+  - test-relay-flow
 cleanupRunnerOnEnd: true
 
 taskConfig:
@@ -33,7 +33,7 @@ nodes:
 
   implement:
     type: agent
-    agent: coding
+    agent: build
     description: Implement the parent story and verify the changes.
     # nudgePrompt: "Finish {{node}} for {{ticket}} and choose one of: {{nextSteps}}"
     taskConfig:
@@ -50,13 +50,13 @@ nodes:
 
   review:
     type: agent
-    agent: review
+    agent: plan
     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
+        taskStatus: In Progress
         # parentStatus: In Review
     onSuccess:
       - target: prReview
@@ -67,13 +67,13 @@ nodes:
 
   prReview:
     type: hitl
-    agent: review
+    agent: plan
     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
+        taskStatus: In Progress
         # parentStatus: In Review
     onSuccess:
       - target: end

package/go.mod

@@ -2,10 +2,11 @@ module github.com/rajpopat27/relay-flow
 
 go 1.24.6
 
-require (
+	require (
 	github.com/cschleiden/go-workflows v1.4.2
 	github.com/google/renameio/v2 v2.0.1
 	github.com/google/uuid v1.6.0
+	github.com/yuin/goldmark v1.7.13
 	gopkg.in/yaml.v3 v3.0.1
 )
 

package/go.sum

@@ -122,6 +122,8 @@ github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOf
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
+github.com/yuin/goldmark v1.7.13 h1:GPddIs617DnBLFFVJFgpo1aBfe/4xcvMc3SB5t/D0pA=
+github.com/yuin/goldmark v1.7.13/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
 go.opentelemetry.io/otel v1.31.0 h1:NsJcKPIW0D0H3NgzPDHmo0WW6SptzPdqg/L1zsIm2hY=
 go.opentelemetry.io/otel v1.31.0/go.mod h1:O0C14Yl9FgkjqcCZAsE053C13OaddMYr/hz6clDkEJE=
 go.opentelemetry.io/otel/metric v1.31.0 h1:FSErL0ATQAmYHUIzSezZibnyVlft1ybhy4ozRPcF2fE=

package/internal/config/config.go

@@ -26,9 +26,9 @@ func Merge(values ...RawValues) RawValues {
 
 func mergeInto(dst, src map[string]any) map[string]any {
 	for k, sv := range src {
-		if sm, ok := sv.(map[string]any); ok {
+		if sm, ok := rawMap(sv); ok {
 			fresh := map[string]any{}
-			if dm, ok := dst[k].(map[string]any); ok {
+			if dm, ok := rawMap(dst[k]); ok {
 				mergeInto(fresh, dm)
 			}
 			dst[k] = mergeInto(fresh, sm)
@@ -39,6 +39,17 @@ func mergeInto(dst, src map[string]any) map[string]any {
 	return dst
 }
 
+func rawMap(value any) (map[string]any, bool) {
+	switch values := value.(type) {
+	case map[string]any:
+		return values, true
+	case RawValues:
+		return map[string]any(values), true
+	default:
+		return nil, false
+	}
+}
+
 // DecodeStrict decodes raw values into dst, rejecting unknown fields and
 // explicit null values.
 func DecodeStrict(values RawValues, dst any) error {

package/internal/config/merge_test.go

@@ -49,6 +49,24 @@ func TestMergeMapsRecursively(t *testing.T) {
 	}
 }
 
+func TestMergeRawValuesMapsRecursively(t *testing.T) {
+	defaults := config.RawValues{"templates": map[string]any{
+		"mailboxDescription": "default mailbox",
+		"summaryComment":     "default summary",
+	}}
+	override := config.RawValues{"templates": config.RawValues{
+		"mailboxDescription": "custom mailbox",
+	}}
+	got := config.Merge(defaults, override)
+	templates, ok := got["templates"].(map[string]any)
+	if !ok {
+		t.Fatalf("templates = %#v", got["templates"])
+	}
+	if templates["mailboxDescription"] != "custom mailbox" || templates["summaryComment"] != "default summary" {
+		t.Fatalf("templates = %#v", templates)
+	}
+}
+
 func TestMergeListReplaces(t *testing.T) {
 	root := config.RawValues{"labels": []any{"a", "b"}}
 	wf := config.RawValues{"labels": []any{"c"}}

package/internal/execution/goworkflows/activities.go

@@ -51,6 +51,16 @@ func (a *Activities) EnsureMailboxes(ctx context.Context, w run.Work, specs []ta
 	if err != nil {
 		return nil, err
 	}
+	for i := range specs {
+		data := specs[i].TextData
+		data.RunID = string(w.RunID)
+		data.Repo = w.Repo
+		custom, err := sys.RenderText(task.TextMailboxDescription, data)
+		if err != nil {
+			return nil, fmt.Errorf("render mailbox %q description: %w", specs[i].Node, err)
+		}
+		specs[i].Description = appendText(custom, specs[i].Description)
+	}
 	return sys.EnsureMailboxes(ctx, w.Parent, w.Workflow, specs)
 }
 
@@ -147,60 +157,65 @@ func (a *Activities) EnsureNodeRuntime(ctx context.Context, nw run.NodeWork, rep
 	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
 	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)
-	}
-	cmd, err := a.Harness.BuildCommand(spec)
-	if err != nil {
-		return err
-	}
 	stored := runner.Terminal{ID: rt.TerminalID, Title: spec.Title}
-	terminal, err := a.Runner.EnsureTerminal(ctx, env, stored, spec.Title, cmd)
+	terminal, live, err := a.Runner.FindTerminal(ctx, stored)
 	if err != nil {
 		return err
 	}
-	// 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)
+	if live {
+		if err := a.Runs.replaceNodeRuntime(ctx, nw.RunID, nw.Node, nw.NodeVisitID,
+			terminal.ID, rt.SessionID, rt.SessionID); err != nil {
+			return err
+		}
+		if !revisit {
+			// Same-visit retry/restart is silent: do not render, build, or send.
+			return nil
+		}
+		prompt, err := a.Harness.RenderPrompt(harness.PromptFeedback, spec.PromptData, spec.NudgePrompt)
+		if err != nil {
+			return err
+		}
+		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
 		}
-		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
+
+	// An initial or replacement terminal resumes the stored session and
+	// receives the rendered initial prompt. Same-visit replacements omit the
+	// node nudge; a new visit includes it.
+	nudge := ""
+	if rt.NodeVisitID == "" || revisit {
+		nudge = spec.NudgePrompt
 	}
-	if err := a.Runner.SendTerminal(ctx, terminal, prompt); err == nil {
-		return nil
+	spec.Prompt, err = a.Harness.RenderPrompt(harness.PromptInitial, spec.PromptData, nudge)
+	if err != nil {
+		return err
 	}
-	// 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 {
+	cmd, err := a.Harness.BuildCommand(spec)
+	if err != nil {
 		return err
 	}
-	replacement, err := a.Runner.EnsureTerminal(ctx, env, terminal, spec.Title, cmd)
+	replacement, err := a.Runner.EnsureTerminal(ctx, env, stored, spec.Title, cmd)
 	if err != nil {
 		return err
 	}
+	// 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,
 		replacement.ID, rt.SessionID, rt.SessionID); err != nil {
-		_ = a.Runner.CloseTerminal(ctx, replacement)
+		if replacement.ID != rt.TerminalID {
+			_ = a.Runner.CloseTerminal(ctx, replacement)
+		}
 		return err
 	}
 	return nil
@@ -276,7 +291,14 @@ func (a *Activities) Comment(ctx context.Context, repoName string, cw run.Commen
 	if err != nil {
 		return err
 	}
-	if err := sys.Comment(ctx, cw.Item, cw.Body, cw.Marker); err != nil {
+	body := cw.Body
+	if cw.TextKind != "" {
+		body, err = sys.RenderText(cw.TextKind, cw.TextData)
+		if err != nil {
+			return fmt.Errorf("render %s: %w", cw.TextKind, err)
+		}
+	}
+	if err := sys.Comment(ctx, cw.Item, body, cw.Marker); err != nil {
 		return err
 	}
 	// Log AFTER the write succeeds so the line is a true effect record.
@@ -395,17 +417,7 @@ 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 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.`)
-	}
-	b.WriteString(`
-
-Required report format:
+	b.WriteString(`Required report format:
 
 STATUS: success | failure
 NEXT STEP: <one valid node name>
@@ -424,7 +436,9 @@ REQUIRED ACTIONS:
 RELEVANT CONTEXT:
 EXPECTED RESULT:
 
-Every field is required; use None for an intentionally empty section. COMMITS must contain the relevant commit IDs or None. NEXT STEP must name exactly one target listed below for your status. When NEXT STEP is end, every FEEDBACK field must be None.`)
+Every field is required; use None for an intentionally empty section. COMMITS must contain the relevant commit IDs or None.
+
+Node names identify workflow stages; they are not task-system statuses. STATUS describes whether the work at this node succeeded or failed, not the status of the parent or mailbox. NEXT STEP must name exactly one target listed below for that STATUS. Submit one report only: its SUMMARY is written to this current mailbox, while its FEEDBACK is written only to the selected next node's mailbox. For review nodes, put requested changes in FEEDBACK and select the node responsible for acting on them. Relay-flow and the task system own parent and mailbox status changes. When NEXT STEP is end, every FEEDBACK field must be None.`)
 	writeRoutes := func(label string, routes []workflow.Route) {
 		if len(routes) == 0 {
 			return
@@ -440,11 +454,20 @@ Every field is required; use None for an intentionally empty section. COMMITS mu
 	}
 	writeRoutes("On success", n.OnSuccess)
 	writeRoutes("On failure", n.OnFailure)
+	successRoutes := routesText(n.OnSuccess)
+	failureRoutes := routesText(n.OnFailure)
 	return task.MailboxSpec{
 		Node:        name,
 		Title:       ticketKey + ":" + name,
 		Description: b.String(),
 		TaskConfig:  n.TaskConfig,
+		TextData: task.TextData{
+			Ticket: ticketKey, Workflow: wf.Name, Node: name, NodeType: string(n.Type),
+			Agent: n.Agent, NodeDescription: n.Description,
+			NextSteps:     nextStepsText(append(append([]workflow.Route{}, n.OnSuccess...), n.OnFailure...)),
+			SuccessRoutes: successRoutes, FailureRoutes: failureRoutes,
+			Mailbox: ticketKey + ":" + name,
+		},
 	}
 }
 
@@ -464,20 +487,46 @@ func MailboxSpecs(wf *workflow.Workflow, ticketKey string) []task.MailboxSpec {
 	return out
 }
 
-// BuildLaunchSpecPrompt points the agent to its parent and isolated mailbox.
-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)
+// RenderMailboxSpecs asks the selected task system to render customizable
+// mailbox text, then appends the fixed report contract and legal routes.
+// It is shared by normal execution and explicit database-loss recovery.
+func RenderMailboxSpecs(sys task.System, w run.Work, wf *workflow.Workflow) ([]task.MailboxSpec, error) {
+	specs := MailboxSpecs(wf, w.Parent.Key)
+	for i := range specs {
+		data := specs[i].TextData
+		data.RunID = string(w.RunID)
+		data.Repo = w.Repo
+		custom, err := sys.RenderText(task.TextMailboxDescription, data)
+		if err != nil {
+			return nil, fmt.Errorf("render mailbox %q description: %w", specs[i].Node, err)
+		}
+		specs[i].Description = appendText(custom, specs[i].Description)
+	}
+	return specs, nil
 }
 
-func followUpPrompt(mailboxKey string) string {
-	return fmt.Sprintf("New feedback was added to the comments section of your mailbox subtask %s. Read it.", mailboxKey)
+func routesText(routes []workflow.Route) string {
+	var b strings.Builder
+	for i, route := range routes {
+		if i > 0 {
+			b.WriteString("\n")
+		}
+		b.WriteString(route.Target)
+		if route.When != "" {
+			b.WriteString(" — when: " + route.When)
+		}
+	}
+	return b.String()
 }
 
-func appendPrompt(prompt, extra string) string {
-	if extra == "" {
-		return prompt
+func appendText(first, second string) string {
+	if first == "" {
+		return second
+	}
+	if second == "" {
+		return first
 	}
-	return prompt + "\n\n" + extra
+	return first + "\n\n" + second
 }
 
 // mergeTaskConfig overlays node task config onto workflow task config using