relay-flow 0.2.11-alpha → 0.3.1-alpha

package/README.md

@@ -24,13 +24,13 @@ same `relay-flow-plugin` package with host-specific entrypoints.
 **OpenCode**
 
 ```sh
-opencode plugin relay-flow-plugin@0.2.11-alpha
+opencode plugin relay-flow-plugin@0.3.1-alpha
 ```
 
 **Pi**
 
 ```sh
-pi install npm:relay-flow-plugin@0.2.11-alpha
+pi install npm:relay-flow-plugin@0.3.1-alpha
 ```
 
 Pi loads the package's `pi.ts` extension from its manifest. Do not add
@@ -160,7 +160,7 @@ OpenCode plugin configuration uses both entrypoints. The server entrypoint is li
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["relay-flow-plugin@0.2.11-alpha"]
+  "plugin": ["relay-flow-plugin@0.3.1-alpha"]
 }
 ```
 
@@ -169,7 +169,7 @@ The native HITL approval entrypoint is listed in `.opencode/tui.json`:
 ```json
 {
   "$schema": "https://opencode.ai/tui.json",
-  "plugin": ["relay-flow-plugin@0.2.11-alpha"]
+  "plugin": ["relay-flow-plugin@0.3.1-alpha"]
 }
 ```
 
@@ -185,7 +185,7 @@ Pi plugin: install the same published package manually in Pi's global package
 settings before starting a Pi harness session:
 
 ```sh
-pi install npm:relay-flow-plugin@0.2.11-alpha
+pi install npm:relay-flow-plugin@0.3.1-alpha
 ```
 
 Relay-flow does not install or configure the package automatically. Pi resolves
@@ -629,7 +629,7 @@ EXPECTED RESULT: ...
 
 The labels above are fixed; configurable templates do not change the parsed report contract. The plugin submits one `report` object containing both lower-camel `summary` and `feedback` objects. Relay-flow validates that complete shape once, renders `summaryReport` through the task system's summary-comment template on the current mailbox, and renders `feedbackReport` through its feedback-comment template on only the selected next mailbox. `None` is the literal marker for an intentionally empty section. When `NEXT STEP` is `end`, every FEEDBACK field must be `None` and no feedback comment is written.
 
-The plugin delivers `{runId, node, reportId, report}` as one JSON object via `relay-flow report` stdin with the shared backoff (initial 2s, factor 2, jitter 0.2, max 5m) until acknowledged. It derives `reportId` from the harness session/message identity. Duplicate/stale reports are acked safely with no repeated graph effects. Invalid agent output is nudged; invalid or missing HITL output stays silent, while a valid HITL report opens the native TUI approval dialog. Relay-flow HITL approval does not use OpenCode's Question tool.
+The plugin delivers `{runId, node, reportId, report}` as one JSON object via `relay-flow report` stdin with the shared backoff (initial 2s, factor 2, jitter 0.2, max 5m) until acknowledged. It derives `reportId` from the harness session/message identity. Duplicate/stale reports are acked safely with no repeated graph effects. Invalid agent output is nudged; ordinary, missing, or empty HITL output stays silent, while partial report-shaped HITL output is corrected and a valid HITL report opens the native TUI approval dialog. Relay-flow HITL approval does not use OpenCode's Question tool.
 
 ---
 

package/cmd/relay-flow/main.go

@@ -180,6 +180,8 @@ Run:
   relay-flow run restart --ticket <key>
   relay-flow run cancel --ticket <key>
 
+Use relay-flow <command> --help for command-specific details.
+
 Examples:
   relay-flow workflow list --json
   relay-flow run get --ticket PAY-101
@@ -235,7 +237,14 @@ func printScopedHelp(args []string, w io.Writer) int {
 	case "init":
 		fmt.Fprintln(w, "Usage: relay-flow init [flags]")
 		fmt.Fprintln(w, "\nInitialize relay-flow and its durable state.")
-		fmt.Fprintln(w, "Flags: --force, --task-plugin, --runner-plugin, --harness-plugin, --executor-plugin")
+		fmt.Fprintln(w, "Flags:")
+		fmt.Fprintln(w, "  --task-plugin <name>              Task-system plugin (required with runner and harness plugin flags).")
+		fmt.Fprintln(w, "  --runner-plugin <name>            Runner plugin (required with task and harness plugin flags).")
+		fmt.Fprintln(w, "  --harness-plugin <name>           Harness plugin (required with task and runner plugin flags).")
+		fmt.Fprintln(w, "  --executor-plugin <name>          Durable executor: goworkflows or temporal.")
+		fmt.Fprintln(w, "  --temporal-address <host:port>    Temporal server address; applies only to --executor-plugin temporal (optional, defaults to localhost:7233).")
+		fmt.Fprintln(w, "  --temporal-namespace <name>       Temporal namespace/team name; applies only to --executor-plugin temporal (required).")
+		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]")
@@ -251,11 +260,15 @@ func printScopedHelp(args []string, w io.Writer) int {
 		fmt.Fprintln(w, "Example: relay-flow report < report.json")
 	case "task":
 		fmt.Fprintln(w, "Usage: relay-flow task <command>")
-		fmt.Fprintln(w, "\nCommands: auth")
+		fmt.Fprintln(w, "\nRun task-system commands through the configured task plugin.")
+		fmt.Fprintln(w, "Commands:")
+		fmt.Fprintln(w, "  auth  Authenticate the configured task-system plugin.")
+		fmt.Fprintln(w, "Use relay-flow task <subcommand> --help for command-specific details.")
 		fmt.Fprintln(w, "Example: relay-flow task auth")
 	case "task auth":
 		fmt.Fprintln(w, "Usage: relay-flow task auth [task-plugin options]")
-		fmt.Fprintln(w, "\nDelegate authentication to the configured task-system plugin.")
+		fmt.Fprintln(w, "\nAuthenticate the configured task-system plugin.")
+		fmt.Fprintln(w, "Arguments: task-plugin options are passed through unchanged; relay-flow adds no flags.")
 		fmt.Fprintln(w, "Example: relay-flow task auth")
 	case "runtime-register":
 		fmt.Fprintln(w, "Usage: relay-flow runtime-register < session.json")
@@ -267,61 +280,143 @@ func printScopedHelp(args []string, w io.Writer) int {
 		fmt.Fprintln(w, "Example: relay-flow version")
 	case "workflow":
 		fmt.Fprintln(w, "Usage: relay-flow workflow <command>")
-		fmt.Fprintln(w, "\nCommands: submit, remove, list, get")
-		fmt.Fprintln(w, "Use relay-flow workflow <command> --help for command-specific flags.")
-		fmt.Fprintln(w, "Example: relay-flow workflow list --json")
+		fmt.Fprintln(w, "\nManage validated workflow definitions and inspect their runs.")
+		fmt.Fprintln(w, "Commands:")
+		fmt.Fprintln(w, "  submit  Create or replace a workflow definition.")
+		fmt.Fprintln(w, "    Usage: relay-flow workflow submit --file <path>")
+		fmt.Fprintln(w, "    Example: relay-flow workflow submit --file workflow.yaml")
+		fmt.Fprintln(w, "  remove  Remove a workflow with no active runs.")
+		fmt.Fprintln(w, "    Usage: relay-flow workflow remove --name <name>")
+		fmt.Fprintln(w, "    Example: relay-flow workflow remove --name basicFlow")
+		fmt.Fprintln(w, "  list    List configured workflows and latest execution summaries.")
+		fmt.Fprintln(w, "    Usage: relay-flow workflow list [--json] [--no-color]")
+		fmt.Fprintln(w, "    Example: relay-flow workflow list --json")
+		fmt.Fprintln(w, "  get     Show a workflow graph and recent runs.")
+		fmt.Fprintln(w, "    Usage: relay-flow workflow get --name <name> [--json] [--no-color]")
+		fmt.Fprintln(w, "    Example: relay-flow workflow get --name basicFlow")
+		fmt.Fprintln(w, "Use relay-flow workflow <subcommand> --help for flag details.")
 	case "workflow submit":
 		fmt.Fprintln(w, "Usage: relay-flow workflow submit --file <path>")
 		fmt.Fprintln(w, "\nCreate or replace a validated workflow definition.")
+		fmt.Fprintln(w, "Flags:")
+		fmt.Fprintln(w, "  --file <path>  Workflow YAML file to submit (required).")
 		fmt.Fprintln(w, "Example: relay-flow workflow submit --file workflow.yaml")
 	case "workflow remove":
 		fmt.Fprintln(w, "Usage: relay-flow workflow remove --name <name>")
 		fmt.Fprintln(w, "\nRemove a workflow with no active runs.")
+		fmt.Fprintln(w, "Flags:")
+		fmt.Fprintln(w, "  --name <name>  Workflow name (required).")
 		fmt.Fprintln(w, "Example: relay-flow workflow remove --name basicFlow")
 	case "workflow list":
 		fmt.Fprintln(w, "Usage: relay-flow workflow list [--json] [--no-color]")
 		fmt.Fprintln(w, "\nList configured workflows and their latest execution summaries.")
+		fmt.Fprintln(w, "Flags:")
+		fmt.Fprintln(w, "  --json      Print stable JSON instead of the human-readable table.")
+		fmt.Fprintln(w, "  --no-color  Disable terminal color decoration.")
 		fmt.Fprintln(w, "Example: relay-flow workflow list --json")
 	case "workflow get":
 		fmt.Fprintln(w, "Usage: relay-flow workflow get --name <name> [--json] [--no-color]")
-		fmt.Fprintln(w, "\nShow validated static graph and recent runs. Use --json for automation.")
+		fmt.Fprintln(w, "\nShow a workflow's validated static graph and recent runs.")
+		fmt.Fprintln(w, "Flags:")
+		fmt.Fprintln(w, "  --name <name>  Workflow name (required).")
+		fmt.Fprintln(w, "  --json         Print stable JSON instead of the human-readable detail view.")
+		fmt.Fprintln(w, "  --no-color     Disable terminal color decoration.")
 		fmt.Fprintln(w, "Example: relay-flow workflow get --name basicFlow")
 	case "repo":
 		fmt.Fprintln(w, "Usage: relay-flow repo <command>")
-		fmt.Fprintln(w, "\nCommands: register, remove, list, get")
-		fmt.Fprintln(w, "Use relay-flow repo <command> --help for command-specific flags.")
-		fmt.Fprintln(w, "Example: relay-flow repo list")
+		fmt.Fprintln(w, "\nManage registered runner repositories and task-system configuration.")
+		fmt.Fprintln(w, "Commands:")
+		fmt.Fprintln(w, "  register  Register a runner repository and its task-system configuration.")
+		fmt.Fprintln(w, "    Usage: relay-flow repo register [--name <name>] [--path <path>] [--set key=value ...]")
+		fmt.Fprintln(w, "    Example (Beads): relay-flow repo register --name payments --path /work/payments --set beadsDir=/work/payments/.beads")
+		fmt.Fprintln(w, "  remove    Remove a registered repository.")
+		fmt.Fprintln(w, "    Usage: relay-flow repo remove --name <name>")
+		fmt.Fprintln(w, "    Example: relay-flow repo remove --name payments")
+		fmt.Fprintln(w, "  list      List registered repositories.")
+		fmt.Fprintln(w, "    Usage: relay-flow repo list")
+		fmt.Fprintln(w, "    Example: relay-flow repo list")
+		fmt.Fprintln(w, "  get       Show one registered repository as JSON.")
+		fmt.Fprintln(w, "    Usage: relay-flow repo get --name <name>")
+		fmt.Fprintln(w, "    Example: relay-flow repo get --name payments")
+		fmt.Fprintln(w, "Use relay-flow repo <subcommand> --help for flag details.")
 	case "repo register":
-		fmt.Fprintln(w, "Usage: relay-flow repo register [--name <name> --path <path> --set key=value]")
+		fmt.Fprintln(w, "Usage: relay-flow repo register [--name <name>] [--path <path>] [--set key=value ...]")
 		fmt.Fprintln(w, "\nRegister a runner repository and task-system configuration.")
-		fmt.Fprintln(w, "Example: relay-flow repo register --name payments --path /work/payments")
-	case "repo remove", "repo get":
-		fmt.Fprintf(w, "Usage: relay-flow %s --name <name>\n", name)
-		fmt.Fprintf(w, "Example: relay-flow %s --name payments\n", name)
+		fmt.Fprintln(w, "Flags:")
+		fmt.Fprintln(w, "  --name <name>       Repository name. Optional for interactive registration; required in flagged/non-interactive mode.")
+		fmt.Fprintln(w, "  --path <path>       Local repository path. Optional for interactive registration; required in flagged/non-interactive mode.")
+		fmt.Fprintln(w, "  --set key=value     Optional, repeatable task-system configuration override. Key and value must be non-empty; duplicate keys are rejected.")
+		fmt.Fprintln(w, "\nInteractive mode: omit --name, --path, and --set; a TTY is required.")
+		fmt.Fprintln(w, "Flagged mode: --name and --path are required. Repeat --set once per task-system key; the selected plugin validates keys and values, and derived keys cannot be overridden.")
+		fmt.Fprintln(w, "Example (Beads): relay-flow repo register --name payments --path /work/payments --set beadsDir=/work/payments/.beads")
+	case "repo remove":
+		fmt.Fprintln(w, "Usage: relay-flow repo remove --name <name>")
+		fmt.Fprintln(w, "\nRemove a registered repository.")
+		fmt.Fprintln(w, "Flags:")
+		fmt.Fprintln(w, "  --name <name>  Registered repository name (required).")
+		fmt.Fprintln(w, "No other flags are supported.")
+		fmt.Fprintln(w, "Example: relay-flow repo remove --name payments")
 	case "repo list":
 		fmt.Fprintln(w, "Usage: relay-flow repo list")
 		fmt.Fprintln(w, "\nList registered repositories.")
+		fmt.Fprintln(w, "Flags: none.")
 		fmt.Fprintln(w, "Example: relay-flow repo list")
+	case "repo get":
+		fmt.Fprintln(w, "Usage: relay-flow repo get --name <name>")
+		fmt.Fprintln(w, "\nShow one registered repository and its task-system configuration as JSON.")
+		fmt.Fprintln(w, "Flags:")
+		fmt.Fprintln(w, "  --name <name>  Registered repository name (required).")
+		fmt.Fprintln(w, "No other flags are supported.")
+		fmt.Fprintln(w, "Example: relay-flow repo get --name payments")
 	case "run":
 		fmt.Fprintln(w, "Usage: relay-flow run <command>")
-		fmt.Fprintln(w, "\nCommands: list, get, restart, cancel")
-		fmt.Fprintln(w, "Use relay-flow run <command> --help for command-specific flags.")
-		fmt.Fprintln(w, "Example: relay-flow run get --ticket PAY-101")
+		fmt.Fprintln(w, "\nInspect and control durable ticket runs.")
+		fmt.Fprintln(w, "Commands:")
+		fmt.Fprintln(w, "  list     List runs, optionally filtered by repository, workflow, ticket, or active state.")
+		fmt.Fprintln(w, "    Usage: relay-flow run list [--repo <name>] [--workflow <name>] [--ticket <key>] [--active] [--json] [--no-color]")
+		fmt.Fprintln(w, "    Example: relay-flow run list --active --json")
+		fmt.Fprintln(w, "  get      Show one run's execution detail and actual step visits.")
+		fmt.Fprintln(w, "    Usage: relay-flow run get --ticket <key> [--json] [--no-color]")
+		fmt.Fprintln(w, "    Example: relay-flow run get --ticket PAY-101")
+		fmt.Fprintln(w, "  restart  Start a fresh attempt for a canceled run.")
+		fmt.Fprintln(w, "    Usage: relay-flow run restart --ticket <key>")
+		fmt.Fprintln(w, "    Example: relay-flow run restart --ticket PAY-101")
+		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, "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]")
-		fmt.Fprintln(w, "\nList durable runs. Use --json for automation.")
+		fmt.Fprintln(w, "\nList durable runs, with optional filters.")
+		fmt.Fprintln(w, "Flags:")
+		fmt.Fprintln(w, "  --repo <name>      Filter by registered repository name.")
+		fmt.Fprintln(w, "  --workflow <name>  Filter by workflow name.")
+		fmt.Fprintln(w, "  --ticket <key>     Filter by task ticket key.")
+		fmt.Fprintln(w, "  --active           Show only active runs.")
+		fmt.Fprintln(w, "  --json             Print stable JSON instead of the human-readable table.")
+		fmt.Fprintln(w, "  --no-color         Disable terminal color decoration.")
 		fmt.Fprintln(w, "Example: relay-flow run list --active --json")
 	case "run get":
 		fmt.Fprintln(w, "Usage: relay-flow run get --ticket <key> [--json] [--no-color]")
 		fmt.Fprintln(w, "\nShow an Argo-shaped execution detail view and actual step visits.")
+		fmt.Fprintln(w, "Flags:")
+		fmt.Fprintln(w, "  --ticket <key>  Task ticket key (required).")
+		fmt.Fprintln(w, "  --json          Print stable JSON instead of the human-readable detail view.")
+		fmt.Fprintln(w, "  --no-color      Disable terminal color decoration.")
 		fmt.Fprintln(w, "Example: relay-flow run get --ticket PAY-101")
 	case "run restart":
 		fmt.Fprintln(w, "Usage: relay-flow run restart --ticket <key>")
 		fmt.Fprintln(w, "\nStart a fresh attempt for a canceled run.")
+		fmt.Fprintln(w, "Flags:")
+		fmt.Fprintln(w, "  --ticket <key>  Task ticket key (required).")
+		fmt.Fprintln(w, "No other flags are supported.")
 		fmt.Fprintln(w, "Example: relay-flow run restart --ticket PAY-101")
 	case "run cancel":
 		fmt.Fprintln(w, "Usage: relay-flow run cancel --ticket <key> [--reason <text>]")
 		fmt.Fprintln(w, "\nPermanently cancel the current execution attempt.")
+		fmt.Fprintln(w, "Flags:")
+		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"`)
 	default:
 		fmt.Fprintf(os.Stderr, "unknown help target: %s\n", name)

package/cmd/relay-flow/observability_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"io"
 	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 	"time"
@@ -43,9 +44,10 @@ func TestRunDetailRendererKeepsPendingAndNestedVisitOrder(t *testing.T) {
 func TestScopedHelpCoversAllCommandLevels(t *testing.T) {
 	for _, args := range [][]string{
 		{"--help"}, {"workflow", "--help"}, {"workflow", "list", "--help"},
-		{"repo", "--help"}, {"repo", "register", "--help"}, {"run", "--help"},
+		{"repo", "--help"}, {"repo", "register", "--help"}, {"repo", "remove", "--help"},
+		{"repo", "get", "--help"}, {"repo", "list", "--help"}, {"run", "--help"},
 		{"run", "get", "--help"}, {"task", "--help"}, {"task", "auth", "--help"},
-		{"serve", "--help"}, {"runtime-register", "--help"}, {"version", "--help"},
+		{"init", "--help"}, {"serve", "--help"}, {"runtime-register", "--help"}, {"version", "--help"},
 	} {
 		var out bytes.Buffer
 		if code := printScopedHelp(args, &out); code != exitOK {
@@ -54,16 +56,126 @@ func TestScopedHelpCoversAllCommandLevels(t *testing.T) {
 		if out.Len() == 0 {
 			t.Fatalf("help %v was empty", args)
 		}
-		if !strings.Contains(out.String(), "Example:") {
+		if !strings.Contains(out.String(), "Example") {
 			t.Fatalf("help %v missing example: %q", args, out.String())
 		}
 	}
-	var example bytes.Buffer
-	if code := printScopedHelp([]string{"run", "get", "--help"}, &example); code != exitOK || !strings.Contains(example.String(), "Example:") {
-		t.Fatalf("run get help missing example: %q", example.String())
+	root := scopedHelp(t, "--help")
+	if !strings.Contains(root, "Use relay-flow <command> --help for command-specific details.") {
+		t.Fatalf("root help missing scoped-help guidance:\n%s", root)
 	}
 }
 
+func TestInitHelpDocumentsTemporalFlags(t *testing.T) {
+	text := scopedHelp(t, "init", "--help")
+	for _, want := range []string{
+		"--executor-plugin <name>",
+		"--temporal-address <host:port>",
+		"--temporal-namespace <name>",
+		"applies only to --executor-plugin temporal",
+	} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("init help missing %q:\n%s", want, text)
+		}
+	}
+}
+
+func TestRepositoryHelpDocumentsGroupAndEverySubcommand(t *testing.T) {
+	group := scopedHelp(t, "repo", "--help")
+	for _, want := range []string{
+		"Manage registered runner repositories and task-system configuration.",
+		"register", "remove", "list", "get",
+		"Usage: relay-flow repo register", "Usage: relay-flow repo remove --name <name>",
+		"Usage: relay-flow repo list", "Usage: relay-flow repo get --name <name>",
+		"Example (Beads):", "beadsDir=/work/payments/.beads",
+		"Use relay-flow repo <subcommand> --help for flag details.",
+	} {
+		if !strings.Contains(group, want) {
+			t.Fatalf("repo group help missing %q:\n%s", want, group)
+		}
+	}
+
+	register := scopedHelp(t, "repo", "register", "--help")
+	for _, want := range []string{
+		"Register a runner repository and task-system configuration.",
+		"--name <name>", "--path <path>", "--set key=value",
+		"Optional for interactive registration", "required in flagged/non-interactive mode",
+		"Interactive mode: omit --name, --path, and --set", "Repeat --set",
+		"duplicate keys are rejected", "derived keys cannot be overridden",
+		"Example (Beads):", "beadsDir=/work/payments/.beads",
+	} {
+		if !strings.Contains(register, want) {
+			t.Fatalf("repo register help missing %q:\n%s", want, register)
+		}
+	}
+	if strings.Contains(register, "component=backend") {
+		t.Fatalf("repo register help advertises a derived Jira component override:\n%s", register)
+	}
+
+	for _, tc := range []struct {
+		name string
+		want []string
+	}{
+		{name: "remove", want: []string{"Remove a registered repository.", "--name <name>", "required", "No other flags are supported.", "Example:"}},
+		{name: "list", want: []string{"List registered repositories.", "Flags: none.", "Example:"}},
+		{name: "get", want: []string{"Show one registered repository", "--name <name>", "required", "No other flags are supported.", "Example:"}},
+	} {
+		text := scopedHelp(t, "repo", tc.name, "--help")
+		for _, want := range tc.want {
+			if !strings.Contains(text, want) {
+				t.Fatalf("repo %s help missing %q:\n%s", tc.name, want, text)
+			}
+		}
+	}
+}
+
+func TestWorkflowRunAndTaskGroupsDescribeTheirSubcommands(t *testing.T) {
+	for _, tc := range []struct {
+		args []string
+		want []string
+	}{
+		{args: []string{"workflow", "--help"}, want: []string{"Manage validated workflow definitions", "workflow submit --file <path>", "workflow remove --name <name>", "workflow list [--json]", "workflow get --name <name>", "<subcommand> --help"}},
+		{args: []string{"run", "--help"}, want: []string{"Inspect and control durable ticket runs.", "run list", "run get", "run restart", "run cancel", "--reason <text>", "<subcommand> --help"}},
+		{args: []string{"task", "--help"}, want: []string{"Run task-system commands", "auth", "task <subcommand> --help"}},
+		{args: []string{"workflow", "submit", "--help"}, want: []string{"--file <path>", "required", "Example:"}},
+		{args: []string{"run", "list", "--help"}, want: []string{"--repo <name>", "--workflow <name>", "--ticket <key>", "--active", "--json", "--no-color", "Example:"}},
+		{args: []string{"task", "auth", "--help"}, want: []string{"task-plugin options are passed through unchanged", "no flags", "Example:"}},
+	} {
+		text := scopedHelp(t, tc.args...)
+		for _, want := range tc.want {
+			if !strings.Contains(text, want) {
+				t.Fatalf("help %v missing %q:\n%s", tc.args, want, text)
+			}
+		}
+	}
+}
+
+func TestScopedHelpDoesNotRequireRelayFlowHomeOrServer(t *testing.T) {
+	home := filepath.Join(t.TempDir(), "missing-home")
+	t.Setenv("RELAY_FLOW_HOME", home)
+	code, output := captureStdout(t, func() int {
+		return run([]string{"repo", "register", "--help"}, strings.NewReader(""))
+	})
+	if code != exitOK {
+		t.Fatalf("help exit = %d, want %d", code, exitOK)
+	}
+	if !strings.Contains(output, "Usage: relay-flow repo register") {
+		t.Fatalf("help output = %q", output)
+	}
+	if _, err := os.Stat(home); !os.IsNotExist(err) {
+		t.Fatalf("help touched relay-flow home: stat error = %v", err)
+	}
+}
+
+func scopedHelp(t *testing.T, args ...string) string {
+	t.Helper()
+	var out bytes.Buffer
+	if code := printScopedHelp(args, &out); code != exitOK {
+		t.Fatalf("help %v exit = %d", args, code)
+	}
+	return out.String()
+}
+
 func TestFilteredEmptyRunListShowsEffectiveFilters(t *testing.T) {
 	var out bytes.Buffer
 	active := true

package/internal/execution/goworkflows/activities.go

@@ -157,7 +157,8 @@ func (a *Activities) LoadNodeRuntime(ctx context.Context, id run.ID, node string
 
 // EnsureNodeRuntime uses only persisted terminal/session IDs on the normal
 // path. A live terminal is rebound to the new visit; otherwise EnsureTerminal
-// creates a replacement and its direct ID is persisted immediately.
+// creates a replacement and its direct ID is persisted immediately. A stored
+// session receives feedback whether its terminal is reused or replaced.
 func (a *Activities) EnsureNodeRuntime(ctx context.Context, nw run.NodeWork, repoPath string, spec harness.LaunchSpec, rt NodeRuntime) error {
 	a.Runs.runtimeMu.Lock()
 	defer a.Runs.runtimeMu.Unlock()
@@ -196,6 +197,10 @@ func (a *Activities) EnsureNodeRuntime(ctx context.Context, nw run.NodeWork, rep
 	rt.TerminalID = currentRuntime.TerminalID
 	rt.SessionID = currentRuntime.SessionID
 	spec.ResumeID = rt.SessionID
+	promptKind := harness.PromptInitial
+	if rt.SessionID != "" {
+		promptKind = harness.PromptFeedback
+	}
 	stored := runner.Terminal{ID: rt.TerminalID, Title: spec.Title}
 	terminal, live, err := a.Runner.FindTerminal(ctx, stored)
 	if err != nil {
@@ -210,7 +215,7 @@ func (a *Activities) EnsureNodeRuntime(ctx context.Context, nw run.NodeWork, rep
 			// 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)
+		prompt, err := a.Harness.RenderPrompt(promptKind, spec.PromptData, spec.NudgePrompt)
 		if err != nil {
 			return err
 		}
@@ -224,14 +229,14 @@ func (a *Activities) EnsureNodeRuntime(ctx context.Context, nw run.NodeWork, rep
 		}
 	}
 
-	// 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.
+	// A fresh session receives the initial prompt; a stored session receives
+	// feedback even when its terminal must be replaced. Same-visit
+	// replacements omit the node nudge; a new visit includes it.
 	nudge := ""
 	if rt.NodeVisitID == "" || revisit {
 		nudge = spec.NudgePrompt
 	}
-	spec.Prompt, err = a.Harness.RenderPrompt(harness.PromptInitial, spec.PromptData, nudge)
+	spec.Prompt, err = a.Harness.RenderPrompt(promptKind, spec.PromptData, nudge)
 	if err != nil {
 		return err
 	}

package/internal/execution/goworkflows/engine_test.go

@@ -369,6 +369,10 @@ func TestEndAppliesConfigAndCompletes(t *testing.T) {
 	if cleanupIdx < endApplyIdx {
 		t.Fatalf("runner cleanup ran before end taskConfig; events=%v", events)
 	}
+	closeIdx := indexOf(events, "closeTerminal:PAY-101:coding")
+	if closeIdx < 0 || cleanupIdx >= closeIdx {
+		t.Fatalf("runner cleanup did not precede runtime finalization: cleanup=%d close=%d events=%v", cleanupIdx, closeIdx, events)
+	}
 	r2, _ := engine.GetRun(context.Background(), rid)
 	if r2.State == run.StateCompleted && r2.FinishedAt == nil {
 		t.Fatal("completed run has no FinishedAt")
@@ -382,6 +386,54 @@ func TestEndAppliesConfigAndCompletes(t *testing.T) {
 	}
 }
 
+func TestEndCleanupRetriesDirtyCheckoutBeforeFinalization(t *testing.T) {
+	log := newEventLog()
+	sys := newFakeTaskSystem(log)
+	fr := newFakeRunner(log)
+	fr.cleanupDirty = true
+	engine := newEngine(t, goworkflows.Dependencies{
+		Repos: repoRegistryWith("payments", sys), Runner: fr, Harness: newFakeHarness(log),
+		Runtime: &run.RuntimePolicy{KeepTerminalsAlive: true, KeepSessionsAlive: true},
+	})
+	rid, _ := startRun(engine, linearWorkflow(true))
+	waitFor(t, 10*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), rid)
+		return r.CurrentNode == "coding"
+	})
+	if _, err := engine.SubmitReport(context.Background(), reportRequest(rid, "coding", successReport("end"))); err != nil {
+		t.Fatal(err)
+	}
+
+	waitFor(t, 10*time.Second, func() bool {
+		return indexOf(log.all(), "cleanupRunDirty:"+string(rid)) >= 0
+	})
+	r, _ := engine.GetRun(context.Background(), rid)
+	if r.State == run.StateCompleted || r.FinishedAt != nil {
+		t.Fatalf("run completed while dirty cleanup was retrying: %+v", r)
+	}
+	if fr.liveTerminals() != 1 {
+		t.Fatalf("dirty cleanup closed the terminal before retry: live=%d events=%v", fr.liveTerminals(), log.all())
+	}
+	if indexOf(log.all(), "closeTerminal:PAY-101:coding") >= 0 {
+		t.Fatalf("runtime finalization ran before dirty cleanup retry: events=%v", log.all())
+	}
+
+	waitFor(t, 10*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), rid)
+		return r.State == run.StateCompleted
+	})
+	events := log.all()
+	dirtyIdx := indexOf(events, "cleanupRunDirty:"+string(rid))
+	cleanupIdx := indexOf(events, "cleanupRun:"+string(rid))
+	closeIdx := indexOf(events, "closeTerminal:PAY-101:coding")
+	if dirtyIdx < 0 || cleanupIdx < 0 || closeIdx < 0 || dirtyIdx >= cleanupIdx || cleanupIdx >= closeIdx {
+		t.Fatalf("cleanup retry/finalization order = %v", events)
+	}
+	if len(fr.cleaned) != 1 {
+		t.Fatalf("successful CleanupRun calls = %v, want one after the dirty retry", fr.cleaned)
+	}
+}
+
 func TestEndCleanupDisabledKeepsRetainedRunner(t *testing.T) {
 	log := newEventLog()
 	fr := newFakeRunner(log)

package/internal/execution/goworkflows/fakes_test.go

@@ -340,13 +340,14 @@ func (s *fakeTaskSystem) parentByKey(key string) (task.Ticket, bool) {
 type fakeRunner struct {
 	log *eventLog
 
-	mu        sync.Mutex
-	envs      map[string]runner.Environment
-	terminals map[string]*fakeTerminal // envID/title
-	cleaned   []string
-	closedRun []string
-	createErr error
-	nextID    int
+	mu           sync.Mutex
+	envs         map[string]runner.Environment
+	terminals    map[string]*fakeTerminal // envID/title
+	cleaned      []string
+	closedRun    []string
+	cleanupDirty bool
+	createErr    error
+	nextID       int
 }
 
 type fakeTerminal struct {
@@ -460,6 +461,11 @@ func (f *fakeRunner) CloseTerminals(_ context.Context, spec runner.RunSpec) erro
 func (f *fakeRunner) CleanupRun(_ context.Context, spec runner.RunSpec) error {
 	f.mu.Lock()
 	defer f.mu.Unlock()
+	if f.cleanupDirty {
+		f.cleanupDirty = false
+		f.log.add("cleanupRunDirty:" + string(spec.RunID))
+		return errDirtyCleanup
+	}
 	prefix := "env-" + spec.TicketKey + "/"
 	for k := range f.terminals {
 		if len(k) >= len(prefix) && k[:len(prefix)] == prefix {
@@ -581,3 +587,4 @@ func (e *conflictError) Error() string { return e.msg }
 
 var errConflict = &conflictError{msg: "human moved mailbox"}
 var errStartConflict = &conflictError{msg: "human moved ticket status"}
+var errDirtyCleanup = &transientError{msg: "ticket checkout is dirty; commit required before runner cleanup"}

package/internal/execution/goworkflows/interpreter.go

@@ -484,13 +484,10 @@ func (a *Activities) runGraph(ctx goworkflow.Context, start run.Start) error {
 	if wf.CleanupRunnerOnEnd {
 		finalPolicy.KeepTerminalsAlive = false
 	}
-	if _, err := retryLoop(ctx, start.ID, a, work, "",
-		func(ctx2 goworkflow.Context) goworkflow.Future[struct{}] {
-			return goworkflow.ExecuteActivity[struct{}](ctx2, noNativeRetries,
-				a.FinalizeNodeRuntimes, work, start.RepoPath, finalPolicy)
-		}); err != nil {
-		return err
-	}
+	// Cleanup must run before finalizing node runtimes when enabled. The
+	// runner performs its Git cleanliness check before closing terminals, so a
+	// dirty checkout leaves the agent terminal available for a commit while
+	// retryLoop waits.
 	if wf.CleanupRunnerOnEnd {
 		if _, err := retryLoop(ctx, start.ID, a, work, "",
 			func(ctx2 goworkflow.Context) goworkflow.Future[struct{}] {
@@ -499,6 +496,13 @@ func (a *Activities) runGraph(ctx goworkflow.Context, start run.Start) error {
 			return err
 		}
 	}
+	if _, err := retryLoop(ctx, start.ID, a, work, "",
+		func(ctx2 goworkflow.Context) goworkflow.Future[struct{}] {
+			return goworkflow.ExecuteActivity[struct{}](ctx2, noNativeRetries,
+				a.FinalizeNodeRuntimes, work, start.RepoPath, finalPolicy)
+		}); err != nil {
+		return err
+	}
 	endFinished := goworkflow.Now(ctx).UTC()
 	endStep.Status, endStep.FinishedAt = run.StepSucceeded, &endFinished
 	if _, err := retryLoop(ctx, start.ID, a, work, "end",

package/internal/execution/goworkflows/node_runtime_test.go

@@ -189,7 +189,7 @@ func TestNodeRuntimeSessionRegistrationKeepsOldSessionBoundToOldVisit(t *testing
 	}
 }
 
-func TestEnsureNodeRuntimeUsesDirectIDsAndFallsBackFresh(t *testing.T) {
+func TestEnsureNodeRuntimeUsesDirectIDsAndResumesWithFeedback(t *testing.T) {
 	ctx := context.Background()
 	fr := &runtimeTestRunner{}
 	fh := &runtimeTestHarness{}
@@ -233,12 +233,12 @@ func TestEnsureNodeRuntimeUsesDirectIDsAndFallsBackFresh(t *testing.T) {
 	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)
+	if !reflect.DeepEqual(fh.rendered, []harness.PromptKind{harness.PromptFeedback}) {
+		t.Fatalf("dead-terminal rendered prompts = %v, want feedback", fh.rendered)
 	}
 	for _, prompt := range fh.prompts {
-		if prompt != "work" {
-			t.Fatalf("same-visit relaunch prompt = %q, want standard prompt only", prompt)
+		if prompt != "feedback" {
+			t.Fatalf("same-visit relaunch prompt = %q, want feedback only", prompt)
 		}
 	}
 }
@@ -363,7 +363,7 @@ func TestEnsureNodeRuntimeSendFailureClosesLiveTerminal(t *testing.T) {
 	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." {
+	if len(fh.prompts) != 1 || fh.prompts[0] != "feedback\n\nRead the latest review feedback." {
 		t.Fatalf("revisit replacement prompt = %q", fh.prompts)
 	}
 	rt, _ := p.getNodeRuntime(ctx, id, "implement")
@@ -373,8 +373,8 @@ 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)
+	if !reflect.DeepEqual(fh.rendered, []harness.PromptKind{harness.PromptFeedback, harness.PromptFeedback}) {
+		t.Fatalf("rendered prompts = %v, want feedback then replacement feedback", fh.rendered)
 	}
 }