relay-flow 0.3.9-alpha → 0.3.11-alpha

package/cmd/relay-flow/main.go

@@ -61,13 +61,25 @@ var (
 	buildDate = "unknown"
 )
 
-func main() { os.Exit(run(os.Args[1:], os.Stdin)) }
+var runningAsMain = false
+
+const serveChildEnvironment = "RELAY_FLOW_SERVE_CHILD"
+
+func main() {
+	runningAsMain = true
+	os.Exit(run(os.Args[1:], os.Stdin))
+}
 
 // home returns the relay-flow root, honoring RELAY_FLOW_HOME (tests and
-// non-standard installs) and falling back to ~/.relay-flow.
+// non-standard installs) and falling back to ~/.relay-flow. The configured
+// root is made absolute so detached children never resolve it through a
+// caller directory that may disappear after launch.
 func home() (paths.Paths, error) {
 	if env := os.Getenv("RELAY_FLOW_HOME"); env != "" {
-		root := env
+		root, err := filepath.Abs(env)
+		if err != nil {
+			return paths.Paths{}, fmt.Errorf("resolve RELAY_FLOW_HOME: %w", err)
+		}
 		return paths.Paths{
 			Root:        root,
 			Config:      filepath.Join(root, "config.yaml"),
@@ -150,6 +162,7 @@ func usage(w io.Writer) {
 
 Usage:
   relay-flow [command] [flags]
+  rf         [command] [flags]  (equivalent executable name)
 
 Setup and server:
   relay-flow init [--force] [--task-plugin <name> --runner-plugin <name> --harness-plugin <name>]
@@ -157,8 +170,13 @@ Setup and server:
                    [--temporal-address <host:port>] [--temporal-namespace <name>]
                    (interactive first run also authenticates and optionally registers repos)
   relay-flow task auth [task-plugin options]
-  relay-flow serve [--recover] [--debug] [--background]
+  relay-flow serve [--recover] [--debug] [--foreground | --background]
   relay-flow stop
+
+  Plain serve starts detached, waits for Unix-socket readiness, and then returns.
+  Use serve --foreground for a blocking process-supervisor/development mode.
+  Detached startup diagnostics are written to ~/.relay-flow/server.log (or
+  $RELAY_FLOW_HOME/server.log when a custom home is configured).
   relay-flow report
   relay-flow version | --version | -v
 
@@ -179,6 +197,7 @@ Run:
   relay-flow run get --ticket <key> [--json]
   relay-flow run restart --ticket <key>
   relay-flow run cancel --ticket <key>
+  relay-flow run backfill-owner --repo <name> --ticket <key> --workflow <name>
 
 Use relay-flow <command> --help for command-specific details.
 
@@ -247,9 +266,12 @@ func printScopedHelp(args []string, w io.Writer) int {
 		fmt.Fprintln(w, "  --force                           Update plugin selections while preserving existing durable state.")
 		fmt.Fprintln(w, "Example: relay-flow init --task-plugin jira --runner-plugin orca --harness-plugin opencode")
 	case "serve":
-		fmt.Fprintln(w, "Usage: relay-flow serve [--recover] [--debug] [--background]")
-		fmt.Fprintln(w, "\nStart the relay-flow server.")
-		fmt.Fprintln(w, "Example: relay-flow serve --background")
+		fmt.Fprintln(w, "Usage: relay-flow serve [--recover] [--debug] [--foreground | --background]")
+		fmt.Fprintln(w, "\nStart relay-flow detached and wait for the Unix socket to become ready.")
+		fmt.Fprintln(w, "  --foreground  Run the server in the current process until stop or signal.")
+		fmt.Fprintln(w, "  --background   Compatibility spelling for the default detached mode.")
+		fmt.Fprintln(w, "The detached server writes diagnostics to ~/.relay-flow/server.log (or RELAY_FLOW_HOME/server.log).")
+		fmt.Fprintln(w, "Examples: rf serve; relay-flow serve --foreground")
 	case "stop":
 		fmt.Fprintln(w, "Usage: relay-flow stop")
 		fmt.Fprintln(w, "\nStop the running relay-flow server.")
@@ -384,6 +406,9 @@ func printScopedHelp(args []string, w io.Writer) int {
 		fmt.Fprintln(w, "  cancel   Permanently cancel the current execution attempt.")
 		fmt.Fprintln(w, "    Usage: relay-flow run cancel --ticket <key> [--reason <text>]")
 		fmt.Fprintln(w, "    Example: relay-flow run cancel --ticket PAY-101 --reason "+`"operator request"`)
+		fmt.Fprintln(w, "  backfill-owner  Explicitly add provenance to a legacy workflow claim.")
+		fmt.Fprintln(w, "    Usage: relay-flow run backfill-owner --repo <name> --ticket <key> --workflow <name>")
+		fmt.Fprintln(w, "    Example: relay-flow run backfill-owner --repo payments --ticket PAY-101 --workflow basicFlow")
 		fmt.Fprintln(w, "Use relay-flow run <subcommand> --help for flag details.")
 	case "run list":
 		fmt.Fprintln(w, "Usage: relay-flow run list [--repo <name>] [--workflow <name>] [--ticket <key>] [--active] [--json] [--no-color]")
@@ -418,6 +443,15 @@ func printScopedHelp(args []string, w io.Writer) int {
 		fmt.Fprintln(w, "  --ticket <key>    Task ticket key (required).")
 		fmt.Fprintln(w, "  --reason <text>   Optional cancellation reason recorded with the request.")
 		fmt.Fprintln(w, "Example: relay-flow run cancel --ticket PAY-101 --reason "+`"operator request"`)
+	case "run backfill-owner":
+		fmt.Fprintln(w, "Usage: relay-flow run backfill-owner --repo <name> --ticket <key> --workflow <name>")
+		fmt.Fprintln(w, "\nExplicitly add adapter-owned provenance to a legacy workflow claim.")
+		fmt.Fprintln(w, "This never removes wf: labels, comments, or history and is not automatic routing.")
+		fmt.Fprintln(w, "Flags:")
+		fmt.Fprintln(w, "  --repo <name>      Registered repository containing the claim (required).")
+		fmt.Fprintln(w, "  --ticket <key>     Task ticket key (required).")
+		fmt.Fprintln(w, "  --workflow <name>  Claimed workflow name (required).")
+		fmt.Fprintln(w, "Example: relay-flow run backfill-owner --repo payments --ticket PAY-101 --workflow basicFlow")
 	default:
 		fmt.Fprintf(os.Stderr, "unknown help target: %s\n", name)
 		return exitUsage
@@ -630,6 +664,10 @@ func cmdInit(p paths.Paths, args []string, stdin io.Reader) int {
 		fmt.Fprintln(os.Stderr, "init: harness plugin: "+err.Error())
 		return exitFail
 	}
+	if names[0] == "jira" {
+		harnessDefaults["initial"] = harness.JiraInitialPrompt
+		harnessDefaults["feedback"] = harness.JiraFeedbackPrompt
+	}
 	if !*force || !configExists {
 		cfg.HarnessConfig = harnessDefaults
 	} else {
@@ -689,7 +727,7 @@ func cmdInit(p paths.Paths, args []string, stdin io.Reader) int {
 				fmt.Fprintln(os.Stderr, "init: "+err.Error())
 				return exitFail
 			}
-			fmt.Println("Repository setup complete. The server is running; stop it with `relay-flow stop`.")
+			fmt.Println("Repository setup complete. The server is running; stop it with `rf stop`.")
 		}
 	} else if err := config.SaveMachine(p.Config, cfg); err != nil {
 		fmt.Fprintln(os.Stderr, err)
@@ -821,11 +859,17 @@ func cmdServe(p paths.Paths, args []string) int {
 	fs := flag.NewFlagSet("serve", flag.ContinueOnError)
 	recover := fs.Bool("recover", false, "treat execution state as lost and rebuild from the task system")
 	debug := fs.Bool("debug", false, "enable debug logging (overrides RELAY_FLOW_LOG_LEVEL)")
-	background := fs.Bool("background", false, "start the server detached and return after readiness")
+	foreground := fs.Bool("foreground", false, "run the server in the current process until stop or signal")
+	background := fs.Bool("background", false, "compatibility spelling for the default detached mode")
 	if err := fs.Parse(args); err != nil {
 		return exitUsage
 	}
-	if *background {
+	child := os.Getenv(serveChildEnvironment) == "1"
+	if *foreground && *background {
+		fmt.Fprintln(os.Stderr, "serve: --foreground and --background cannot be used together")
+		return exitUsage
+	}
+	if !*foreground && !child {
 		if err := startBackgroundServe(p, *recover, *debug); err != nil {
 			fmt.Fprintln(os.Stderr, err)
 			return exitFail
@@ -833,6 +877,12 @@ func cmdServe(p paths.Paths, args []string) int {
 		fmt.Println("Relay-flow server started")
 		return exitOK
 	}
+	if runningAsMain {
+		if err := anchorForegroundServe(p.Root); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+	}
 	logCloser, err := logging.Setup(p.ServerLog, logging.Options{
 		Debug: *debug,
 		Env:   os.Getenv("RELAY_FLOW_LOG_LEVEL"),
@@ -858,6 +908,9 @@ var (
 )
 
 func startBackgroundServe(p paths.Paths, recover, debug bool) error {
+	if err := ensureStableServeDirectory(p.Root); err != nil {
+		return fmt.Errorf("serve --background: prepare working directory: %w", err)
+	}
 	client := server.NewClient(p.Socket)
 	if serverResponding(client, 200*time.Millisecond) {
 		return fmt.Errorf("serve --background: server is already running")
@@ -869,36 +922,57 @@ func startBackgroundServe(p paths.Paths, recover, debug bool) error {
 	}
 
 	var (
-		cmd           *exec.Cmd
-		wait          chan error
-		observedOwner = lockHeld
-		devNull       *os.File
+		cmd             *exec.Cmd
+		wait            chan error
+		testServeCancel chan struct{}
+		observedOwner   = lockHeld
+		devNull         *os.File
 	)
 	if !lockHeld {
-		executable, resolveErr := os.Executable()
-		if resolveErr != nil {
-			return fmt.Errorf("serve --background: resolve executable: %w", resolveErr)
-		}
-		childArgs := []string{"serve"}
-		if recover {
-			childArgs = append(childArgs, "--recover")
-		}
-		if debug {
-			childArgs = append(childArgs, "--debug")
-		}
-		devNull, err = os.OpenFile(os.DevNull, os.O_RDWR, 0)
-		if err != nil {
-			return fmt.Errorf("serve --background: open %s: %w", os.DevNull, err)
-		}
-		defer devNull.Close()
-		cmd = exec.Command(executable, childArgs...)
-		cmd.Stdin, cmd.Stdout, cmd.Stderr = devNull, devNull, devNull
-		cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
-		if err := cmd.Start(); err != nil {
-			return fmt.Errorf("serve --background: start: %w; see %s", err, p.ServerLog)
-		}
 		wait = make(chan error, 1)
-		go func() { wait <- cmd.Wait() }()
+		if !runningAsMain {
+			// The run(args, stdin) seam is used by in-process tests. A Go test
+			// executable is not the relay-flow CLI entrypoint, so spawning
+			// os.Executable here would recursively run the test suite. Keep the
+			// production path detached while using the same serveRoot path in
+			// that seam.
+			serveCtx := &inProcessServeContext{Context: context.Background(), done: make(chan struct{})}
+			testServeCancel = serveCtx.done
+			go func() {
+				logCloser, logErr := logging.Setup(p.ServerLog, logging.Options{
+					Debug: debug,
+					Env:   os.Getenv("RELAY_FLOW_LOG_LEVEL"),
+				})
+				if logErr != nil {
+					wait <- logErr
+					return
+				}
+				defer logCloser.Close()
+				wait <- serveRoot(serveCtx, p, recover)
+			}()
+		} else {
+			executable, resolveErr := os.Executable()
+			if resolveErr != nil {
+				return fmt.Errorf("serve --background: resolve executable: %w", resolveErr)
+			}
+			childArgs := serveChildArgs(recover, debug)
+			devNull, err = os.OpenFile(os.DevNull, os.O_RDWR, 0)
+			if err != nil {
+				return fmt.Errorf("serve --background: open %s: %w", os.DevNull, err)
+			}
+			defer devNull.Close()
+			cmd = exec.Command(executable, childArgs...)
+			cmd.Dir = p.Root
+			childEnvironment := setEnvironment(os.Environ(), serveChildEnvironment, "1")
+			childEnvironment = setEnvironment(childEnvironment, "PWD", p.Root)
+			cmd.Env = setEnvironment(childEnvironment, "RELAY_FLOW_HOME", p.Root)
+			cmd.Stdin, cmd.Stdout, cmd.Stderr = devNull, devNull, devNull
+			cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
+			if err := cmd.Start(); err != nil {
+				return fmt.Errorf("serve --background: start: %w; see %s", err, p.ServerLog)
+			}
+			go func() { wait <- cmd.Wait() }()
+		}
 	}
 
 	ticker := time.NewTicker(backgroundServePollInterval)
@@ -908,6 +982,10 @@ func startBackgroundServe(p paths.Paths, recover, debug bool) error {
 			return nil
 		}
 		if !time.Now().Before(deadline) {
+			if testServeCancel != nil {
+				close(testServeCancel)
+				testServeCancel = nil
+			}
 			if cmd != nil && wait != nil {
 				_ = cmd.Process.Kill()
 				<-wait
@@ -925,6 +1003,7 @@ func startBackgroundServe(p paths.Paths, recover, debug bool) error {
 		}
 		select {
 		case childErr := <-wait:
+			testServeCancel = nil
 			held, lockErr := serverLockHeld(p.Lock)
 			if lockErr != nil {
 				return fmt.Errorf("serve --background: inspect server lock: %w", lockErr)
@@ -943,6 +1022,80 @@ func startBackgroundServe(p paths.Paths, recover, debug bool) error {
 	}
 }
 
+func serveChildArgs(recover, debug bool) []string {
+	args := []string{"serve"}
+	if recover {
+		args = append(args, "--recover")
+	}
+	if debug {
+		args = append(args, "--debug")
+	}
+	return args
+}
+
+type inProcessServeContext struct {
+	context.Context
+	done chan struct{}
+}
+
+func (c *inProcessServeContext) Done() <-chan struct{} {
+	return c.done
+}
+
+func (c *inProcessServeContext) Err() error {
+	select {
+	case <-c.done:
+		return context.Canceled
+	default:
+		return nil
+	}
+}
+
+func setEnvironment(environment []string, key, value string) []string {
+	prefix := key + "="
+	out := make([]string, 0, len(environment)+1)
+	for _, entry := range environment {
+		if strings.HasPrefix(entry, prefix) {
+			continue
+		}
+		out = append(out, entry)
+	}
+	return append(out, prefix+value)
+}
+
+func ensureStableServeDirectory(root string) error {
+	if err := os.MkdirAll(root, 0o700); err != nil {
+		return err
+	}
+	if err := os.Chmod(root, 0o700); err != nil {
+		return err
+	}
+	info, err := os.Stat(root)
+	if err != nil {
+		return err
+	}
+	if !info.IsDir() {
+		return fmt.Errorf("%s is not a directory", root)
+	}
+	return nil
+}
+
+func anchorForegroundServe(root string) error {
+	if err := ensureStableServeDirectory(root); err != nil {
+		return err
+	}
+	if err := os.Chdir(root); err != nil {
+		return fmt.Errorf("anchor working directory at %s: %w", root, err)
+	}
+	if err := os.Setenv("PWD", root); err != nil {
+		return fmt.Errorf("set working directory environment at %s: %w", root, err)
+	}
+	if err := os.Setenv("RELAY_FLOW_HOME", root); err != nil {
+		return fmt.Errorf("set relay-flow home environment at %s: %w", root, err)
+	}
+	return nil
+}
+
 func serverLockHeld(path string) (bool, error) {
 	f, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0o600)
 	if err != nil {
@@ -1400,6 +1553,23 @@ func cmdRun(c *server.Client, args []string) int {
 			return exitFail
 		}
 		return exitOK
+	case "backfill-owner":
+		fs := flag.NewFlagSet("run backfill-owner", flag.ContinueOnError)
+		repoName := fs.String("repo", "", "registered repository name")
+		ticket := fs.String("ticket", "", "ticket key")
+		workflowName := fs.String("workflow", "", "workflow name")
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		if *repoName == "" || *ticket == "" || *workflowName == "" {
+			fmt.Fprintln(os.Stderr, "run backfill-owner: --repo, --ticket, and --workflow are required")
+			return exitUsage
+		}
+		if err := c.BackfillClaimOwner(context.Background(), *repoName, *ticket, *workflowName); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		return exitOK
 	}
 	usage(os.Stderr)
 	return exitUsage

package/cmd/relay-flow/observability_test.go

@@ -64,6 +64,17 @@ func TestScopedHelpCoversAllCommandLevels(t *testing.T) {
 	if !strings.Contains(root, "Use relay-flow <command> --help for command-specific details.") {
 		t.Fatalf("root help missing scoped-help guidance:\n%s", root)
 	}
+	for _, want := range []string{
+		"Plain serve starts detached",
+		"Unix-socket readiness",
+		"serve --foreground",
+		"blocking process-supervisor/development mode",
+		"server.log",
+	} {
+		if !strings.Contains(root, want) {
+			t.Fatalf("root help missing serve startup guidance %q:\n%s", want, root)
+		}
+	}
 }
 
 func TestInitHelpDocumentsTemporalFlags(t *testing.T) {

package/cmd/relay-flow/onboarding.go

@@ -337,7 +337,7 @@ func standaloneRepoServerHint(err error) error {
 	message := err.Error()
 	for _, marker := range []string{"dial unix", "connect: no such file or directory", "connection refused"} {
 		if strings.Contains(message, marker) {
-			return fmt.Errorf("%w; start the server with `relay-flow serve --background` (or use the guided init path)", err)
+			return fmt.Errorf("%w; start the server with `rf serve` (or use the guided init path; use `relay-flow serve --foreground` when a blocking process is required)", err)
 		}
 	}
 	return err

package/cmd/relay-flow/onboarding_test.go

@@ -496,7 +496,7 @@ func TestRunOnboardingSpinner(t *testing.T) {
 
 func TestStandaloneRepoServerHint(t *testing.T) {
 	err := standaloneRepoServerHint(errors.New("server call GET /repos: dial unix /tmp/server.sock: connect: no such file or directory"))
-	if err == nil || !containsAll(err.Error(), "serve --background", "guided init") {
+	if err == nil || !containsAll(err.Error(), "rf serve", "guided init") {
 		t.Fatalf("server hint = %v", err)
 	}
 	original := errors.New("server bad request")

package/cmd/relay-flow/scenario_test.go

@@ -839,6 +839,18 @@ func (s *scenarioTaskSystem) CompileFilter(config.RawValues) (func(task.Ticket)
 	return func(t task.Ticket) bool { return t.Key == scenarioTicket }, nil
 }
 
+func (s *scenarioTaskSystem) CompileOwnershipFilter(config.RawValues) (func(task.Ticket) bool, error) {
+	return func(task.Ticket) bool { return true }, nil
+}
+
+func (s *scenarioTaskSystem) ValidateOwnership(context.Context, task.TicketRef, string, config.RawValues) error {
+	return nil
+}
+
+func (s *scenarioTaskSystem) ClaimIfOwned(ctx context.Context, ref task.TicketRef, workflowName string, _ config.RawValues) error {
+	return s.Claim(ctx, ref, workflowName)
+}
+
 func (s *scenarioTaskSystem) Claim(_ context.Context, ref task.TicketRef, workflowName string) error {
 	s.log.add("claim:" + ref.Key + ":" + workflowName)
 	s.mu.Lock()
@@ -1200,19 +1212,23 @@ func (h *scenarioHarness) BuildCommand(spec harness.LaunchSpec) (runner.Command,
 	h.sessions[spec.Title] = harness.Session{ID: "session-" + spec.Title, Title: spec.Title}
 	h.mu.Unlock()
 	h.log.add("harness-launched:" + spec.Title)
+	env := map[string]string{
+		"RELAY_FLOW_RUN_ID":          string(spec.RunID),
+		"RELAY_FLOW_WORKFLOW":        spec.Workflow,
+		"RELAY_FLOW_REPO":            spec.RepoName,
+		"RELAY_FLOW_TICKET":          spec.Ticket,
+		"RELAY_FLOW_NODE":            spec.Node,
+		"RELAY_FLOW_NODE_TYPE":       string(spec.NodeType),
+		"RELAY_FLOW_NUDGE_PROMPT":    spec.NudgePrompt,
+		"RELAY_FLOW_NEXT_STEPS_JSON": routesJSON(spec.NextSteps),
+	}
+	if spec.NodeType == workflow.NodeHITL {
+		env["RELAY_FLOW_AUTO_REJECT"] = fmt.Sprintf("%t", spec.AutoReject)
+	}
 	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,
-			"RELAY_FLOW_REPO":            spec.RepoName,
-			"RELAY_FLOW_TICKET":          spec.Ticket,
-			"RELAY_FLOW_NODE":            spec.Node,
-			"RELAY_FLOW_NODE_TYPE":       string(spec.NodeType),
-			"RELAY_FLOW_NUDGE_PROMPT":    spec.NudgePrompt,
-			"RELAY_FLOW_NEXT_STEPS_JSON": routesJSON(spec.NextSteps),
-		},
+		Env:        env,
 	}, nil
 }
 

package/cmd/relay-flow/serve.go

@@ -541,6 +541,17 @@ func workflowSubmissionValidator(repoReg *repo.Registry, rnr runner.Runner, hrn
 			if _, err := rp.TaskSystem.CompileFilter(wf.TaskConfig); err != nil {
 				return fmt.Errorf("workflow %q repo %q: compile filter: %w", wf.Name, repoName, err)
 			}
+			capabilities, ok := rp.TaskSystem.(task.OwnershipCapabilities)
+			if !ok {
+				return fmt.Errorf("workflow %q repo %q: task system lacks required ownership capabilities", wf.Name, repoName)
+			}
+			ownership, err := capabilities.CompileOwnershipFilter(wf.TaskConfig)
+			if err != nil {
+				return fmt.Errorf("workflow %q repo %q: compile ownership filter: %w", wf.Name, repoName, err)
+			}
+			if ownership == nil {
+				return fmt.Errorf("workflow %q repo %q: ownership compiler returned a nil matcher", wf.Name, repoName)
+			}
 			for nodeName, node := range wf.Nodes {
 				if (node.Type != workflow.NodeAgent && node.Type != workflow.NodeHITL) || node.Agent == "" {
 					continue
@@ -650,6 +661,15 @@ func (d *serveDeps) RestartRun(ctx context.Context, ticket string) (runsvc.Run,
 func (d *serveDeps) CancelRun(ctx context.Context, ticket, reason string) error {
 	return d.runManager.CancelByTicket(ctx, ticket, reason)
 }
+func (d *serveDeps) BackfillClaimOwner(ctx context.Context, repoName, ticket, workflowName string) error {
+	if err := d.runManager.BackfillClaimOwner(ctx, repoName, ticket, workflowName); err != nil {
+		if errors.Is(err, task.ErrOwnershipMismatch) {
+			return fmt.Errorf("%w: %v", server.ErrConflict, err)
+		}
+		return err
+	}
+	return nil
+}
 
 func (d *serveDeps) SubmitReport(ctx context.Context, rep runsvc.ReportRequest) (runsvc.ReportAck, error) {
 	return d.engine.SubmitReport(ctx, rep)
@@ -720,15 +740,21 @@ func handleBatch(runManager *runsvc.RunManager) repo.BatchHandler {
 			case err != nil:
 				var amb *router.AmbiguousError
 				var inv *router.InvalidClaimError
+				var ownerMismatch *router.ClaimOwnerMismatchError
 				outcome := "error"
+				workflowName := ""
 				switch {
 				case errors.As(err, &amb):
 					outcome = "ambiguous"
 				case errors.As(err, &inv):
 					outcome = "invalid-claim"
+					workflowName = inv.Workflow
+				case errors.As(err, &ownerMismatch):
+					outcome = "claim-owner-mismatch"
+					workflowName = ownerMismatch.Workflow
 				}
 				slog.Info("route outcome",
-					"repo", rp.Name, "ticket", ticket.Key, "outcome", outcome, "error", err)
+					"repo", rp.Name, "ticket", ticket.Key, "workflow", workflowName, "outcome", outcome, "error", err)
 				continue
 			}
 			routeOutcome := "claimed"

package/examples/config-reference.yaml

@@ -42,21 +42,19 @@ taskConfig:
   #   parentStatus: In Progress
   #   taskStatus: In Progress
 
-  # Task-system text templates. The fixed report contract is appended by
-  # relay-flow and is not changed by these templates.
+  # Jira mailbox descriptions include the canonical report through {{report}}.
   templates:
     mailboxDescription: |-
-      Parent ticket: {{ticket}}
-      Workflow: {{workflow}}
-      Node: {{node}}
-      Node type: {{nodeType}}
-      Agent: {{agent}}
-      Mailbox: {{mailbox}}
-
-      Node work:
+      {{ticket}} / {{node}} — {{nodeType}} — {{agent}}
       {{nodeDescription}}
 
-      Read this mailbox's comments for feedback from previous nodes.
+      Success routes:
+      {{successRoutes}}
+
+      Failure routes:
+      {{failureRoutes}}
+
+      {{report}}
 
     summaryComment: |-
       Summary for {{node}}
@@ -80,14 +78,19 @@ harnessPlugin: opencode
 harnessConfig:
   # OpenCode supports initial, feedback, and hitl templates.
   initial: |-
-    Task system: {{taskSystem}}
-    Use the {{taskSystem}} tools to read the parent ticket {{ticket}}.
+    Read the description of your assigned Jira task:
+    acli jira workitem view "{{mailbox}}" --fields "summary,description" --json
 
-    Your mailbox is {{mailbox}}. Read its description and comments for node instructions and feedback.
+    Follow the work instructions, valid routes, and report format in that description.
 
   feedback: |-
-    New feedback was added to the comments section of your mailbox subtask {{mailbox}}. Read it.
+    Continue {{node}} from the latest update on your assigned Jira task:
+    acli jira workitem comment list --key "{{mailbox}}" --limit 1 --order "-created" --json
 
+  # A node needing parent details can request this additional instruction
+  # in its node description (it is not included by default):
+  # Read the parent Jira ticket for this step:
+  # acli jira workitem view "{{ticket}}" --fields "summary,description" --json
   hitl: |-
     Return the complete report directly. Relay-flow will show a native TUI approval dialog after the report is valid. Do not use OpenCode's Question tool for relay-flow approval.
 
@@ -135,12 +138,13 @@ repos:
 # harnessPlugin: pi
 # harnessConfig:
 #   initial: |
-#     Task system: {{taskSystem}}
-#     Use the {{taskSystem}} tools to read the parent ticket {{ticket}}.
+#     Read the description of your assigned Jira task:
+#     acli jira workitem view "{{mailbox}}" --fields "summary,description" --json
 #
-#     Your mailbox is {{mailbox}}. Read its description and comments for node instructions and feedback.
+#     Follow the work instructions, valid routes, and report format in that description.
 #   feedback: |
-#     New feedback was added to the comments section of your mailbox subtask {{mailbox}}. Read it.
+#     Continue {{node}} from the latest update on your assigned Jira task:
+#     acli jira workitem comment list --key "{{mailbox}}" --limit 1 --order "-created" --json
 #
 # Pi accepts only initial and feedback harness templates. Pi workflow nodes
 # may use agent: default or a native project prompt template in

package/examples/workflow-reference.yaml

@@ -56,6 +56,9 @@ nodes:
     type: agent
     agent: build
     description: |
+      Read the parent Jira ticket for this step:
+      acli jira workitem view "{{ticket}}" --fields "summary,description" --json
+
       Implement the parent ticket in the ticket worktree.
       Run the relevant tests and verification commands.
     nudgePrompt: |

package/internal/execution/goworkflows/activities.go

@@ -80,7 +80,11 @@ func (a *Activities) EnsureMailboxes(ctx context.Context, w run.Work, specs []ta
 		if err != nil {
 			return nil, fmt.Errorf("render mailbox %q description: %w", specs[i].Node, err)
 		}
-		specs[i].Description = appendText(custom, specs[i].Description)
+		if data.Report != "" && strings.Contains(custom, data.Report) {
+			specs[i].Description = custom
+		} else {
+			specs[i].Description = appendText(custom, specs[i].Description)
+		}
 	}
 	return sys.EnsureMailboxes(ctx, w.Parent, w.Workflow, specs)
 }
@@ -488,26 +492,9 @@ func MailboxSpecForNode(wf *workflow.Workflow, ticketKey, name string, n workflo
 	var b strings.Builder
 	b.WriteString(`Required report format:
 
-STATUS: success | failure
-NEXT STEP: <one valid node name>
-
-SUMMARY:
-COMPLETED:
-COMMITS:
-NOT COMPLETED:
-ISSUES DISCOVERED:
-VERIFICATION:
-NOTES:
-
-FEEDBACK:
-REASON FOR NEXT STEP:
-REQUIRED ACTIONS:
-RELEVANT CONTEXT:
-EXPECTED RESULT:
+` + workflow.ReportFormat + `
 
-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.`)
+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, FEEDBACK must be None.`)
 	writeRoutes := func(label string, routes []workflow.Route) {
 		if len(routes) == 0 {
 			return
@@ -535,7 +522,7 @@ Node names identify workflow stages; they are not task-system statuses. STATUS d
 			Agent: n.Agent, NodeDescription: n.Description,
 			NextSteps:     nextStepsText(append(append([]workflow.Route{}, n.OnSuccess...), n.OnFailure...)),
 			SuccessRoutes: successRoutes, FailureRoutes: failureRoutes,
-			Mailbox: ticketKey + ":" + name,
+			Mailbox: ticketKey + ":" + name, Report: workflow.ReportFormat,
 		},
 	}
 }
@@ -569,7 +556,11 @@ func RenderMailboxSpecs(sys task.System, w run.Work, wf *workflow.Workflow) ([]t
 		if err != nil {
 			return nil, fmt.Errorf("render mailbox %q description: %w", specs[i].Node, err)
 		}
-		specs[i].Description = appendText(custom, specs[i].Description)
+		if data.Report != "" && strings.Contains(custom, data.Report) {
+			specs[i].Description = custom
+		} else {
+			specs[i].Description = appendText(custom, specs[i].Description)
+		}
 	}
 	return specs, nil
 }