relay-flow 0.2.0-alpha → 0.2.2-alpha

package/internal/harness/opencode/opencode_test.go

@@ -1,13 +1,21 @@
 package opencode_test
 
 import (
+	"encoding/json"
+	"os"
+	"path/filepath"
 	"reflect"
+	"strings"
 	"testing"
 
+	"github.com/rajpopat27/relay-flow/internal/config"
 	"github.com/rajpopat27/relay-flow/internal/harness"
 	"github.com/rajpopat27/relay-flow/internal/harness/opencode"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
+const configuredPlugin = "relay-flow-plugin@0.2.2-alpha"
+
 func TestBuildCommandArgv(t *testing.T) {
 	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")
 	tests := []struct {
@@ -48,3 +56,178 @@ func TestBuildCommandArgv(t *testing.T) {
 		})
 	}
 }
+
+func TestRenderPromptTemplatesExposeAllValues(t *testing.T) {
+	raw := config.RawValues{
+		"initial":  "initial {{taskSystem}}|{{ticket}}|{{workflow}}|{{repo}}|{{node}}|{{nodeType}}|{{agent}}|{{nodeDescription}}|{{nextSteps}}|{{mailbox}}",
+		"feedback": "feedback {{mailbox}}",
+		"hitl":     "hitl {{node}}",
+	}
+	h, err := harness.New("opencode", raw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	data := harness.PromptData{
+		TaskSystem: "linear", Ticket: "PAY-101", Workflow: "basicFlow", Repo: "payments",
+		Node: "review", NodeType: workflow.NodeHITL, Agent: "build", NodeDescription: "Review it.",
+		NextSteps: "end (when: approved)", Mailbox: "PAY-234",
+	}
+	nudge := "nudge {{taskSystem}}|{{ticket}}|{{workflow}}|{{repo}}|{{node}}|{{nextSteps}}"
+	initial, err := h.RenderPrompt(harness.PromptInitial, data, nudge)
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantInitial := "initial linear|PAY-101|basicFlow|payments|review|hitl|build|Review it.|end (when: approved)|PAY-234\n\nhitl review\n\nnudge linear|PAY-101|basicFlow|payments|review|end (when: approved)"
+	if initial != wantInitial {
+		t.Fatalf("initial prompt = %q, want %q", initial, wantInitial)
+	}
+	feedback, err := h.RenderPrompt(harness.PromptFeedback, data, nudge)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := "feedback PAY-234\n\nhitl review\n\nnudge linear|PAY-101|basicFlow|payments|review|end (when: approved)"; feedback != want {
+		t.Fatalf("feedback prompt = %q, want %q", feedback, want)
+	}
+}
+
+func TestHarnessConfigRejectsUnknownPromptVariable(t *testing.T) {
+	_, err := harness.New("opencode", config.RawValues{"initial": "{{unknown}}"})
+	if err == nil || !strings.Contains(err.Error(), "unknown template variable {{unknown}}") {
+		t.Fatalf("harness.New error = %v", err)
+	}
+}
+
+func TestSetupRepoCreatesOpenCodeJSON(t *testing.T) {
+	dir := t.TempDir()
+	setupTwice(t, dir)
+	path := filepath.Join(dir, "opencode.json")
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var cfg struct {
+		Plugin []string `json:"plugin"`
+	}
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		t.Fatalf("created config is invalid JSON: %v\n%s", err, data)
+	}
+	if !reflect.DeepEqual(cfg.Plugin, []string{configuredPlugin}) {
+		t.Fatalf("plugin = %v", cfg.Plugin)
+	}
+}
+
+func TestSetupRepoUpdatesExistingJSONAndPreservesContent(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "opencode.json")
+	original := "{\n  \"theme\": \"catppuccin\",\n  \"plugin\": [\"keep-me\", \"relay-flow-plugin@0.1.0\"],\n  \"nested\": {\"enabled\": true}\n}\n"
+	if err := os.WriteFile(path, []byte(original), 0o640); err != nil {
+		t.Fatal(err)
+	}
+	setupTwice(t, dir)
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var cfg struct {
+		Theme  string          `json:"theme"`
+		Plugin []string        `json:"plugin"`
+		Nested map[string]bool `json:"nested"`
+	}
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		t.Fatalf("updated config is invalid JSON: %v\n%s", err, data)
+	}
+	if cfg.Theme != "catppuccin" || !cfg.Nested["enabled"] {
+		t.Fatalf("existing config changed: %+v", cfg)
+	}
+	if !reflect.DeepEqual(cfg.Plugin, []string{"keep-me", configuredPlugin}) {
+		t.Fatalf("plugin = %v", cfg.Plugin)
+	}
+	info, err := os.Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if info.Mode().Perm() != 0o640 {
+		t.Fatalf("mode = %o, want 640", info.Mode().Perm())
+	}
+}
+
+func TestSetupRepoUpdatesJSONCOnceAndPreservesComments(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "opencode.jsonc")
+	original := `{
+  // theme stays
+  "theme": "catppuccin",
+  "plugin": [
+    "keep-me", // existing plugin stays
+    "relay-flow-plugin",
+    /* duplicate old relay-flow entry */
+    "relay-flow-plugin@0.1.0",
+  ],
+  "nested": {"enabled": true}, // trailing comment stays
+}
+`
+	if err := os.WriteFile(path, []byte(original), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	setupTwice(t, dir)
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(data)
+	for _, preserved := range []string{"// theme stays", "// existing plugin stays", "/* duplicate old relay-flow entry */", "// trailing comment stays", "\"keep-me\"", "\"nested\": {\"enabled\": true}"} {
+		if !strings.Contains(text, preserved) {
+			t.Fatalf("config lost %q:\n%s", preserved, text)
+		}
+	}
+	if strings.Count(text, configuredPlugin) != 1 || strings.Contains(text, "relay-flow-plugin@0.1.0") {
+		t.Fatalf("relay-flow plugin not updated exactly once:\n%s", text)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "opencode.json")); !os.IsNotExist(err) {
+		t.Fatalf("unexpected opencode.json created: %v", err)
+	}
+}
+
+func TestSetupRepoAddsPluginPropertyToJSONCWithComments(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "opencode.jsonc")
+	original := "{\n  \"theme\": \"catppuccin\" // keep at end\n}\n"
+	if err := os.WriteFile(path, []byte(original), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	setupTwice(t, dir)
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(data)
+	if !strings.Contains(text, "// keep at end") || strings.Count(text, configuredPlugin) != 1 {
+		t.Fatalf("config not preserved and updated:\n%s", text)
+	}
+}
+
+func setupTwice(t *testing.T, dir string) {
+	t.Helper()
+	h := opencode.New()
+	if err := h.SetupRepo(t.Context(), dir); err != nil {
+		t.Fatalf("first SetupRepo: %v", err)
+	}
+	path := filepath.Join(dir, "opencode.json")
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		path = filepath.Join(dir, "opencode.jsonc")
+	}
+	first, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := h.SetupRepo(t.Context(), dir); err != nil {
+		t.Fatalf("second SetupRepo: %v", err)
+	}
+	second, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(first, second) {
+		t.Fatalf("SetupRepo is not idempotent\nfirst:\n%s\nsecond:\n%s", first, second)
+	}
+}

package/internal/harness/opencode/repo_setup.go

@@ -0,0 +1,361 @@
+package opencode
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+)
+
+const relayFlowPlugin = "relay-flow-plugin@0.2.2-alpha"
+
+type jsoncToken struct {
+	kind       byte
+	start, end int
+	value      string
+}
+
+type jsoncValue struct {
+	kind       byte
+	startToken int
+	endToken   int
+	members    []jsoncMember
+	elements   []jsoncValue
+	closeToken int
+}
+
+type jsoncMember struct {
+	name  string
+	value jsoncValue
+}
+
+type jsoncParser struct {
+	tokens []jsoncToken
+	index  int
+}
+
+type textEdit struct {
+	start, end int
+	text       string
+}
+
+func setupRepo(repoPath string) error {
+	path, mode, err := openCodeConfigPath(repoPath)
+	if err != nil {
+		return err
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if !os.IsNotExist(err) {
+			return fmt.Errorf("opencode: read %s: %w", path, err)
+		}
+		data = []byte("{\n  \"plugin\": [\"" + relayFlowPlugin + "\"]\n}\n")
+	} else {
+		data, err = updateOpenCodeConfig(data)
+		if err != nil {
+			return fmt.Errorf("opencode: update %s: %w", path, err)
+		}
+	}
+	if existing, readErr := os.ReadFile(path); readErr == nil && string(existing) == string(data) {
+		return nil
+	}
+	if err := config.WriteAtomic(path, data, mode); err != nil {
+		return fmt.Errorf("opencode: write config: %w", err)
+	}
+	return nil
+}
+
+func openCodeConfigPath(repoPath string) (string, os.FileMode, error) {
+	jsonPath := filepath.Join(repoPath, "opencode.json")
+	jsoncPath := filepath.Join(repoPath, "opencode.jsonc")
+	for _, path := range []string{jsonPath, jsoncPath} {
+		info, err := os.Stat(path)
+		if err == nil {
+			if !info.Mode().IsRegular() {
+				return "", 0, fmt.Errorf("opencode: config %s is not a regular file", path)
+			}
+			return path, info.Mode().Perm(), nil
+		}
+		if !os.IsNotExist(err) {
+			return "", 0, fmt.Errorf("opencode: inspect %s: %w", path, err)
+		}
+	}
+	return jsonPath, 0o644, nil
+}
+
+func updateOpenCodeConfig(data []byte) ([]byte, error) {
+	tokens, err := tokenizeJSONC(data)
+	if err != nil {
+		return nil, err
+	}
+	p := jsoncParser{tokens: tokens}
+	root, err := p.parseValue()
+	if err != nil {
+		return nil, err
+	}
+	if p.index != len(tokens) || root.kind != '{' {
+		return nil, fmt.Errorf("config root must be one JSON object")
+	}
+
+	var plugins *jsoncValue
+	for i := range root.members {
+		if root.members[i].name == "plugin" {
+			if plugins != nil {
+				return nil, fmt.Errorf("duplicate plugin property")
+			}
+			plugins = &root.members[i].value
+		}
+	}
+	quoted, _ := json.Marshal(relayFlowPlugin)
+	if plugins == nil {
+		return addPluginProperty(data, tokens, root, string(quoted)), nil
+	}
+	if plugins.kind != '[' {
+		return nil, fmt.Errorf("plugin property must be an array")
+	}
+
+	first := -1
+	duplicates := make([]int, 0)
+	for i, element := range plugins.elements {
+		tok := tokens[element.startToken]
+		if element.kind != 's' {
+			return nil, fmt.Errorf("plugin array element %d must be a string", i)
+		}
+		if tok.value == "relay-flow-plugin" || strings.HasPrefix(tok.value, "relay-flow-plugin@") {
+			if first < 0 {
+				first = i
+			} else {
+				duplicates = append(duplicates, i)
+			}
+		}
+	}
+
+	edits := make([]textEdit, 0, len(duplicates)+1)
+	if first < 0 {
+		edits = append(edits, addArrayElementEdit(tokens, *plugins, string(quoted)))
+	} else {
+		tok := tokens[plugins.elements[first].startToken]
+		edits = append(edits, textEdit{start: tok.start, end: tok.end, text: string(quoted)})
+		for _, index := range duplicates {
+			element := plugins.elements[index]
+			comma := commaBefore(tokens, plugins.elements[index-1].endToken, element.startToken)
+			edits = append(edits,
+				textEdit{start: tokens[comma].start, end: tokens[comma].end},
+				textEdit{start: tokens[element.startToken].start, end: tokens[element.endToken].end},
+			)
+		}
+	}
+	return applyTextEdits(data, edits), nil
+}
+
+func addPluginProperty(data []byte, tokens []jsoncToken, root jsoncValue, quoted string) []byte {
+	closeAt := tokens[root.closeToken].start
+	edits := []textEdit{{
+		start: closeAt,
+		end:   closeAt,
+		text:  "\n  \"plugin\": [" + quoted + "]\n",
+	}}
+	if len(root.members) > 0 {
+		last := root.members[len(root.members)-1].value.endToken
+		if commaBefore(tokens, last, root.closeToken) < 0 {
+			at := tokens[last].end
+			edits = append(edits, textEdit{start: at, end: at, text: ","})
+		}
+	}
+	return applyTextEdits(data, edits)
+}
+
+func addArrayElementEdit(tokens []jsoncToken, array jsoncValue, quoted string) textEdit {
+	if len(array.elements) == 0 {
+		at := tokens[array.closeToken].start
+		return textEdit{start: at, end: at, text: quoted}
+	}
+	last := array.elements[len(array.elements)-1]
+	if comma := commaBefore(tokens, last.endToken, array.closeToken); comma >= 0 {
+		at := tokens[comma].end
+		return textEdit{start: at, end: at, text: " " + quoted}
+	}
+	at := tokens[last.endToken].end
+	return textEdit{start: at, end: at, text: ", " + quoted}
+}
+
+func commaBefore(tokens []jsoncToken, after, before int) int {
+	for i := after + 1; i < before; i++ {
+		if tokens[i].kind == ',' {
+			return i
+		}
+	}
+	return -1
+}
+
+func applyTextEdits(data []byte, edits []textEdit) []byte {
+	for i := 0; i < len(edits); i++ {
+		for j := i + 1; j < len(edits); j++ {
+			if edits[j].start > edits[i].start {
+				edits[i], edits[j] = edits[j], edits[i]
+			}
+		}
+	}
+	out := append([]byte(nil), data...)
+	for _, edit := range edits {
+		out = append(out[:edit.start], append([]byte(edit.text), out[edit.end:]...)...)
+	}
+	return out
+}
+
+func tokenizeJSONC(data []byte) ([]jsoncToken, error) {
+	tokens := make([]jsoncToken, 0)
+	for i := 0; i < len(data); {
+		switch data[i] {
+		case ' ', '\t', '\r', '\n':
+			i++
+			continue
+		case '/':
+			if i+1 >= len(data) {
+				return nil, fmt.Errorf("unexpected slash at byte %d", i)
+			}
+			if data[i+1] == '/' {
+				i += 2
+				for i < len(data) && data[i] != '\n' {
+					i++
+				}
+				continue
+			}
+			if data[i+1] == '*' {
+				start := i
+				i += 2
+				for i+1 < len(data) && !(data[i] == '*' && data[i+1] == '/') {
+					i++
+				}
+				if i+1 >= len(data) {
+					return nil, fmt.Errorf("unterminated comment at byte %d", start)
+				}
+				i += 2
+				continue
+			}
+			return nil, fmt.Errorf("unexpected slash at byte %d", i)
+		case '{', '}', '[', ']', ':', ',':
+			tokens = append(tokens, jsoncToken{kind: data[i], start: i, end: i + 1})
+			i++
+		case '"':
+			start := i
+			i++
+			for i < len(data) {
+				if data[i] == '\\' {
+					i += 2
+					continue
+				}
+				if data[i] == '"' {
+					i++
+					break
+				}
+				i++
+			}
+			if i > len(data) || data[i-1] != '"' {
+				return nil, fmt.Errorf("unterminated string at byte %d", start)
+			}
+			var value string
+			if err := json.Unmarshal(data[start:i], &value); err != nil {
+				return nil, fmt.Errorf("invalid string at byte %d: %w", start, err)
+			}
+			tokens = append(tokens, jsoncToken{kind: 's', start: start, end: i, value: value})
+		default:
+			start := i
+			for i < len(data) && !strings.ContainsRune(" \t\r\n{}[]:,/", rune(data[i])) {
+				i++
+			}
+			if start == i || !json.Valid(data[start:i]) {
+				return nil, fmt.Errorf("invalid value at byte %d", start)
+			}
+			tokens = append(tokens, jsoncToken{kind: 'v', start: start, end: i})
+		}
+	}
+	return tokens, nil
+}
+
+func (p *jsoncParser) parseValue() (jsoncValue, error) {
+	if p.index >= len(p.tokens) {
+		return jsoncValue{}, fmt.Errorf("expected value")
+	}
+	start := p.index
+	tok := p.tokens[p.index]
+	switch tok.kind {
+	case 's', 'v':
+		p.index++
+		return jsoncValue{kind: tok.kind, startToken: start, endToken: start}, nil
+	case '{':
+		return p.parseObject()
+	case '[':
+		return p.parseArray()
+	default:
+		return jsoncValue{}, fmt.Errorf("unexpected token %q at byte %d", tok.kind, tok.start)
+	}
+}
+
+func (p *jsoncParser) parseObject() (jsoncValue, error) {
+	value := jsoncValue{kind: '{', startToken: p.index}
+	p.index++
+	for {
+		if p.index >= len(p.tokens) {
+			return jsoncValue{}, fmt.Errorf("unterminated object")
+		}
+		if p.tokens[p.index].kind == '}' {
+			value.closeToken = p.index
+			value.endToken = p.index
+			p.index++
+			return value, nil
+		}
+		key := p.tokens[p.index]
+		if key.kind != 's' {
+			return jsoncValue{}, fmt.Errorf("object key at byte %d must be a string", key.start)
+		}
+		p.index++
+		if p.index >= len(p.tokens) || p.tokens[p.index].kind != ':' {
+			return jsoncValue{}, fmt.Errorf("object key %q is missing a colon", key.value)
+		}
+		p.index++
+		memberValue, err := p.parseValue()
+		if err != nil {
+			return jsoncValue{}, err
+		}
+		value.members = append(value.members, jsoncMember{name: key.value, value: memberValue})
+		if p.index < len(p.tokens) && p.tokens[p.index].kind == ',' {
+			p.index++
+			continue
+		}
+		if p.index >= len(p.tokens) || p.tokens[p.index].kind != '}' {
+			return jsoncValue{}, fmt.Errorf("object member %q is missing a comma", key.value)
+		}
+	}
+}
+
+func (p *jsoncParser) parseArray() (jsoncValue, error) {
+	value := jsoncValue{kind: '[', startToken: p.index}
+	p.index++
+	for {
+		if p.index >= len(p.tokens) {
+			return jsoncValue{}, fmt.Errorf("unterminated array")
+		}
+		if p.tokens[p.index].kind == ']' {
+			value.closeToken = p.index
+			value.endToken = p.index
+			p.index++
+			return value, nil
+		}
+		element, err := p.parseValue()
+		if err != nil {
+			return jsoncValue{}, err
+		}
+		value.elements = append(value.elements, element)
+		if p.index < len(p.tokens) && p.tokens[p.index].kind == ',' {
+			p.index++
+			continue
+		}
+		if p.index >= len(p.tokens) || p.tokens[p.index].kind != ']' {
+			return jsoncValue{}, fmt.Errorf("array element is missing a comma")
+		}
+	}
+}

package/internal/harness/plugin_selection_test.go

@@ -20,9 +20,9 @@ import (
 // panics.
 
 func TestHarnessRegistryUnknownNameListsRegistered(t *testing.T) {
-	harness.Register("fakeharness-unknown", func(config.RawValues) (harness.Harness, error) {
+	harness.Register("fakeharness-unknown", harness.Factory{New: func(config.RawValues) (harness.Harness, error) {
 		return newFakeHarness(), nil
-	})
+	}})
 	_, err := harness.New("does-not-exist", config.RawValues{})
 	if err == nil {
 		t.Fatal("unknown harness name accepted")
@@ -75,9 +75,9 @@ func TestDuplicateRegistrationPanics(t *testing.T) {
 		fn()
 	}
 
-	harness.Register("dup-harness-x", func(config.RawValues) (harness.Harness, error) { return nil, nil })
+	harness.Register("dup-harness-x", harness.Factory{New: func(config.RawValues) (harness.Harness, error) { return nil, nil }})
 	assertPanic("harness", func() {
-		harness.Register("dup-harness-x", func(config.RawValues) (harness.Harness, error) { return nil, nil })
+		harness.Register("dup-harness-x", harness.Factory{New: func(config.RawValues) (harness.Harness, error) { return nil, nil }})
 	})
 
 	runner.Register("dup-runner-x", func(config.RawValues) (runner.Runner, error) { return nil, nil })
@@ -97,7 +97,7 @@ func TestDuplicateRegistrationPanics(t *testing.T) {
 func TestNamesListsRegistered(t *testing.T) {
 	// Self-contained: register fixtures within this test rather than relying
 	// on earlier tests in the binary.
-	harness.Register("names-harness-x", func(config.RawValues) (harness.Harness, error) { return nil, nil })
+	harness.Register("names-harness-x", harness.Factory{New: func(config.RawValues) (harness.Harness, error) { return nil, nil }})
 	runner.Register("names-runner-x", func(config.RawValues) (runner.Runner, error) { return nil, nil })
 	task.Register("names-task-x", task.Factory{
 		RequiredRepoKeys: func() []string { return nil },

package/internal/paths/paths.go

@@ -10,14 +10,15 @@ import (
 
 // Paths is the fixed ~/.relay-flow layout. All process artifacts stay under Root.
 type Paths struct {
-	Root      string
-	Config    string
-	Workflows string
-	Database  string
-	Socket    string
-	Lock      string
-	ServerLog string
-	PluginLog string
+	Root        string
+	Config      string
+	Credentials string
+	Workflows   string
+	Database    string
+	Socket      string
+	Lock        string
+	ServerLog   string
+	PluginLog   string
 }
 
 // ForUserHome returns the Paths rooted at the current user's home directory.
@@ -28,14 +29,15 @@ func ForUserHome() (Paths, error) {
 	}
 	root := filepath.Join(home, ".relay-flow")
 	return Paths{
-		Root:      root,
-		Config:    filepath.Join(root, "config.yaml"),
-		Workflows: filepath.Join(root, "workflows"),
-		Database:  filepath.Join(root, "state.db"),
-		Socket:    filepath.Join(root, "server.sock"),
-		Lock:      filepath.Join(root, "server.lock"),
-		ServerLog: filepath.Join(root, "server.log"),
-		PluginLog: filepath.Join(root, "plugin.log"),
+		Root:        root,
+		Config:      filepath.Join(root, "config.yaml"),
+		Credentials: filepath.Join(root, "credentials.yaml"),
+		Workflows:   filepath.Join(root, "workflows"),
+		Database:    filepath.Join(root, "state.db"),
+		Socket:      filepath.Join(root, "server.sock"),
+		Lock:        filepath.Join(root, "server.lock"),
+		ServerLog:   filepath.Join(root, "server.log"),
+		PluginLog:   filepath.Join(root, "plugin.log"),
 	}, nil
 }
 

package/internal/recover/recover.go

@@ -37,11 +37,10 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
-// MailboxSpecFor builds one spec per agent/HITL work node for a ticket. The
-// engine's MailboxSpecs supplies the production description content; this
+// MailboxSpecFor builds and task-system-renders one spec per work node. This
 // indirection keeps recover decoupled from the engine package (which imports
 // internal/run and would otherwise form a cycle).
-type MailboxSpecFor func(wf *workflow.Workflow, ticketKey string) []task.MailboxSpec
+type MailboxSpecFor func(task.System, run.Work, *workflow.Workflow) ([]task.MailboxSpec, error)
 
 // FromTaskSystem is the `serve --recover` composition. Explicit flag only;
 // never automatic; database loss is never inferred.
@@ -84,9 +83,15 @@ func FromTaskSystem(ctx context.Context, repoReg *repo.Registry, rnr runner.Runn
 			}); err != nil {
 				return fmt.Errorf("repo %q ticket %s close terminals: %w", rp.Name, ticket.Key, err)
 			}
-			// EnsureMailboxes: find existing, create only missing. Specs are
-			// built by the caller (the engine supplies production content).
-			mailboxes, err := rp.TaskSystem.EnsureMailboxes(ctx, ticket.Ref(), wf.Name, specsFor(wf, ticket.Key))
+			// EnsureMailboxes: find existing, create only missing. The selected
+			// task system renders its customizable description before the fixed
+			// report contract and legal routes are supplied.
+			work := run.Work{RunID: runID, Repo: rp.Name, Workflow: wf.Name, Parent: ticket.Ref(), WorkflowTaskConfig: wf.TaskConfig}
+			specs, err := specsFor(rp.TaskSystem, work, wf)
+			if err != nil {
+				return fmt.Errorf("repo %q ticket %s render mailboxes: %w", rp.Name, ticket.Key, err)
+			}
+			mailboxes, err := rp.TaskSystem.EnsureMailboxes(ctx, ticket.Ref(), wf.Name, specs)
 			if err != nil {
 				return fmt.Errorf("repo %q ticket %s ensure mailboxes: %w", rp.Name, ticket.Key, err)
 			}