relay-flow 0.3.9-alpha → 0.3.11-alpha

package/README.md

@@ -16,6 +16,10 @@ Install the latest released CLI with Homebrew:
 brew install rajpopat27/tap/relay-flow
 ```
 
+The package installs both equivalent commands, `relay-flow` and `rf`. The
+short `rf` name is also included in release archives and can be installed by
+`install.sh` or with `go install ./cmd/relay-flow ./cmd/rf` from a checkout.
+
 ### 2. Install the harness extension
 
 Choose the harness that will run your agent sessions. Both commands install the
@@ -24,13 +28,13 @@ same `relay-flow-plugin` package with host-specific entrypoints.
 **OpenCode**
 
 ```sh
-opencode plugin relay-flow-plugin@0.3.9-alpha
+opencode plugin relay-flow-plugin@0.3.11-alpha
 ```
 
 **Pi**
 
 ```sh
-pi install npm:relay-flow-plugin@0.3.9-alpha
+pi install npm:relay-flow-plugin@0.3.11-alpha
 ```
 
 Pi loads the package's `pi.ts` extension from its manifest. Do not add
@@ -62,7 +66,7 @@ relay-flow init \
   --runner-plugin orca \
   --harness-plugin opencode
 relay-flow task auth
-relay-flow serve --background
+rf serve
 ```
 
 For Beads, skip `task auth` and initialize/authenticate the Beads workspace
@@ -84,7 +88,7 @@ For Herdr, register the repository path directly; relay-flow creates ticket
 worktrees lazily. The interactive registration asks for the task-system values
 required by the selected task plugin. `repo register` remains the standalone
 escape hatch for adding repositories after initialization and requires a
-running `relay-flow serve --background`.
+running `rf serve` (or `relay-flow serve`).
 
 ### 5. Submit a workflow
 
@@ -160,7 +164,7 @@ OpenCode plugin configuration uses both entrypoints. The server entrypoint is li
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["relay-flow-plugin@0.3.9-alpha"]
+  "plugin": ["relay-flow-plugin@0.3.11-alpha"]
 }
 ```
 
@@ -169,7 +173,7 @@ The native HITL approval entrypoint is listed in `.opencode/tui.json`:
 ```json
 {
   "$schema": "https://opencode.ai/tui.json",
-  "plugin": ["relay-flow-plugin@0.3.9-alpha"]
+  "plugin": ["relay-flow-plugin@0.3.11-alpha"]
 }
 ```
 
@@ -185,7 +189,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.3.9-alpha
+pi install npm:relay-flow-plugin@0.3.11-alpha
 ```
 
 Relay-flow does not install or configure the package automatically. Pi resolves
@@ -221,7 +225,7 @@ For scripts and existing installations, keep the independent sequence:
 ```sh
 relay-flow init --task-plugin jira --runner-plugin orca --harness-plugin opencode
 relay-flow task auth --site https://company.atlassian.net --email you@example.com --token "$JIRA_API_TOKEN"
-relay-flow serve --background
+rf serve
 ```
 
 `task auth` delegates to the selected task plug-in. Jira prompts for its site,
@@ -262,12 +266,11 @@ workflows/<name>.yaml 0644  submitted workflow definitions
 
 The guided first-run flow can start the server and open repository registration
 for you. `repo register` remains a server-backed standalone command for later
-additions: if no server is running, start it with
-`relay-flow serve --background` (or rerun interactive `relay-flow init` for a
-new home).
+additions: if no server is running, start it with `rf serve` (or rerun
+interactive `relay-flow init` for a new home).
 
 ```sh
-relay-flow serve --background
+rf serve
 ```
 
 The repo must already exist in the runner. For the Orca runner, add it first
@@ -402,13 +405,18 @@ Outside that flow, `repo register` and `workflow submit` require the server to
 already be running; the same process polls repos and drives runs.
 
 ```sh
-relay-flow serve              # normal start; requires an initialized database
-relay-flow serve --background # detached; returns after the server is ready
-relay-flow serve --recover    # explicit destructive rebuild from the task system
-relay-flow stop
+rf serve                    # detached by default; waits for readiness
+relay-flow serve --foreground # blocking mode for supervisors and development
+relay-flow serve --background # compatibility spelling for detached startup
+rf serve --recover           # explicit destructive rebuild from the task system
+rf stop
 ```
 
-`--background` preserves `--debug` and `--recover`, logs to `~/.relay-flow/server.log`, and remains stoppable with `relay-flow stop`. Plain `serve` remains foreground and blocking.
+Both executable names share the same home, socket, lock, database, logs, exit
+codes, and server lifecycle. Detached startup logs diagnostics to
+`~/.relay-flow/server.log` and does not inherit a temporary or deleted caller
+working directory. Use `--foreground` only when the process supervisor owns
+the server lifetime; `--background` remains accepted for existing scripts.
 
 `serve --recover` treats ALL SQLite execution state as gone, closes surviving run-owned terminals (preserving worktrees and code), resets Jira parent+mailbox state, and starts every labeled parent in a fresh deterministic run from `start` with fresh `nodeVisitID`s. Recovery never runs automatically; database loss is never inferred.
 
@@ -606,28 +614,16 @@ durable run waiting; Pi does not require an LLM Question tool for this step.
 
 ## Structured node report
 
-Every visit (agent or HITL) submits one report with the same fixed labels:
+Every visit (agent or HITL) submits one report with four fixed fields:
 
 ```
 STATUS: success | failure
-NEXT STEP: <one configured route for that status>
-
-SUMMARY:
-COMPLETED: ...
-COMMITS: <commit IDs or None>
-NOT COMPLETED: ... | None
-ISSUES DISCOVERED: ... | None
-VERIFICATION: ...
-NOTES: ... | None
-
-FEEDBACK:
-REASON FOR NEXT STEP: ...
-REQUIRED ACTIONS: ...
-RELEVANT CONTEXT: ...
-EXPECTED RESULT: ...
+NEXT STEP: <one valid route>
+SUMMARY: <concise result>
+FEEDBACK: <concise handoff, or None when NEXT STEP is end>
 ```
 
-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 report format is hardcoded, exposed as `{{report}}` in Jira mailbox templates and passed to the runtime plugin through `RELAY_FLOW_REPORT_FORMAT`; configurable templates do not change it. The plugin maps `SUMMARY` to `report.summary.completed` and `FEEDBACK` to `report.feedback.requiredActions`, filling the remaining internal JSON fields with `None`. Relay-flow validates the structured report and writes the current summary to its mailbox and only the selected feedback to the next mailbox. When `NEXT STEP` is `end`, `FEEDBACK` must be exactly `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; 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.